Install the Buf CLI#

Install the Buf CLI on macOS or Linux with Homebrew:

This installs:

• The binaries buf, protoc-gen-buf-breaking, and protoc-gen-buf-lint.
• Bash, fish, and zsh completion for buf.

Install the Buf CLI with Scoop:

To update:

Or with WinGet:

To update:

For raw binaries on x86_64 or arm64, download from GitHub Releases.

Install the Buf CLI as a project-local dependency from npm:

This installs buf, protoc-gen-buf-breaking, and protoc-gen-buf-lint under node_modules/.bin. Invoke them through npx:

Or wire buf commands into package.json scripts.

The Buf CLI is published from the bufbuild/buf repository as either a single binary or a tarball that includes shell completions. See the Releases page for the current version.

Binary only

To install just the buf binary to /usr/local/bin:

/usr/local/bin should be on your $PATH. To uninstall:

Tarball with completions, manpages, and protoc plugins

To install buf, protoc-gen-buf-breaking, protoc-gen-buf-lint, shell completions, and manpages to /usr/local:

The binaries land in ${PREFIX}/bin, which should be on your $PATH. Completions land in ${PREFIX}/share/{fish,zsh}/..., manpages in ${PREFIX}/share/man/man1. To uninstall:

The Buf CLI ships as a Docker image at bufbuild/buf:

The image’s ENTRYPOINT is buf, so omit buf from the docker run invocation.

The image doesn’t include protoc or any plugins. Remote plugins work without further configuration. For a protoc-based generation pipeline, see Extending the Docker image below.

Install from source with go install:

The go install command above ignores any local go.mod file, so the resolved dependencies match the versions Buf builds with. Don’t install Buf via tools.go or go tool: those approaches resolve Buf’s dependencies against your project’s, which causes incompatibilities when Buf and your project pin different versions of a shared module.