Skip to content

Install the Buf CLI

The Buf CLI is a developer tool that enables building and management of Protobuf APIs through the command line. It's easy to install, compatible with macOS, Windows, and Linux, and designed to improve the developer experience of working with Protobuf files. You can use the Buf CLI to:

  • Lint, format, and detect breaking changes in your Protobuf files
  • Generate code stubs for multiple languages
  • Manage dependencies on other Protobuf files
  • Integrate Protobuf management and maintenance with your workflow

To install the CLI, you can either use an installation script, or download and extract an archive file from the command line that corresponds to the version of your operating system.

You can install buf on macOS or Linux using Homebrew:

$ brew install bufbuild/buf/buf

This installs:

  • The binaries buf, protoc-gen-buf-breaking, protoc-gen-buf-lint.
  • Bash completion for buf.
  • Fish completion for buf.
  • Zsh completion for buf.

buf is available via npm:

$ npm install @bufbuild/buf

This installs the binaries buf, protoc-gen-buf-breaking, and protoc-gen-buf-lint to be used within your project.

To execute buf from the command line, you can use npx:

npx buf --version

buf is released via the bufbuild/buf repository.

Two types of assets are available:

  • The single buf, protoc-gen-buf-breaking, and protoc-gen-buf-lint binaries.
  • A tarball containing the binaries, bash completion, fish completion, and zsh completion.

See the Releases page for the current release.

Binary

The binary is all you need to get started.

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

# Substitute BIN for your bin directory.
# Substitute VERSION for the current released version.
BIN="/usr/local/bin" && \
VERSION="1.47.2" && \
curl -sSL \
"https://github.com/bufbuild/buf/releases/download/v${VERSION}/buf-$(uname -s)-$(uname -m)" \
-o "${BIN}/buf" && \
chmod +x "${BIN}/buf"

/usr/local/bin should be on your $PATH.

To uninstall from /usr/local/bin:

# Substitute BIN for your bin directory.
BIN="/usr/local/bin" && \
rm -f "${BIN}/buf"

Tarball

To install the buf, protoc-gen-buf-breaking, and protoc-gen-buf-lint inaries, bash completion, fish completion, and zsh completion to /usr/local for version 1.47.2:

# Substitute PREFIX for your install prefix.
# Substitute VERSION for the current released version.
PREFIX="/usr/local" && \
VERSION="1.47.2" && \
curl -sSL \
"https://github.com/bufbuild/buf/releases/download/v${VERSION}/buf-$(uname -s)-$(uname -m).tar.gz" | \
tar -xvzf - -C "${PREFIX}" --strip-components 1

The binaries are installed to /usr/local/bin, which should be on your $PATH.

To uninstall from /usr/local:

# Substitute PREFIX for your install prefix.
PREFIX="/usr/local" && \
rm -f \
"${PREFIX}/bin/buf" \
"${PREFIX}/bin/protoc-gen-buf-breaking" \
"${PREFIX}/bin/protoc-gen-buf-lint" \
"${PREFIX}/etc/bash_completion.d/buf" \
"${PREFIX}/etc/fish/vendor_completions.d/buf.fish"
"${PREFIX}/etc/zsh/site-functions/_buf"

Verifying a release

Releases are signed using our minisign public key:

RWQ/i9xseZwBVE7pEniCNjlNOeeyp4BQgdZDLQcAohxEAH5Uj5DEKjv6

The release assets can be verified using this command (assuming that minisign is installed):

# Download and verify the checksum file for the release
# Substitute VERSION for the current released version.
VERSION="1.47.2" && \
curl -OL https://github.com/bufbuild/buf/releases/download/v${VERSION}/sha256.txt && \
curl -OL https://github.com/bufbuild/buf/releases/download/v${VERSION}/sha256.txt.minisig && \
minisign -Vm sha256.txt -P RWQ/i9xseZwBVE7pEniCNjlNOeeyp4BQgdZDLQcAohxEAH5Uj5DEKjv6

# Download the file(s) you want to verify, for example the tarball
VERSION="1.47.2" && \
curl -OL \
"https://github.com/bufbuild/buf/releases/download/v${VERSION}/buf-$(uname -s)-$(uname -m).tar.gz"

# Verify the file checksums
cat sha256.txt | shasum -a 256 -c --ignore-missing

The binary can be installed from source if go is installed. However, we recommend using one of the release assets instead.

# On Windows
# Substitute GOBIN for your bin directory
# Leave unset to default to %GOPATH%\bin
GO111MODULE=on GOBIN=C:\dev\go\bin go install github.com/bufbuild/buf/cmd/buf@v1.47.2

Buf ships a Docker image (bufbuild/buf) that enables you to use buf as part of your Docker workflow.

For example, you can run buf lint with this command:

$ docker run --volume "$(pwd):/workspace" --workdir /workspace bufbuild/buf lint

You can install the Buf CLI using the Scoop installer for Windows:

scoop install buf

To update Buf:

scoop update buf

Binary

Buf offers Windows binaries for both the x86_64 and arm64 architectures. You can download the latest binaries from GitHub Releases.

Next steps