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
,
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
, andprotoc-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 that is needed to get started.
To install just the buf
binary to /usr/local/bin
for version 1.45.0
:
# Substitute BIN for your bin directory.
# Substitute VERSION for the current released version.
BIN="/usr/local/bin" && \
VERSION="1.45.0" && \
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
binaries, bash completion, fish completion, and zsh completion to /usr/local
for version 1.45.0
:
# Substitute PREFIX for your install prefix.
# Substitute VERSION for the current released version.
PREFIX="/usr/local" && \
VERSION="1.45.0" && \
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.45.0" && \
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.45.0" && \
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.
# Substitute GOBIN for your bin directory
# Leave unset to default to $GOPATH/bin
GO111MODULE=on GOBIN=/usr/local/bin go install \
github.com/bufbuild/buf/cmd/buf@v1.45.0
# 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.45.0
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
Outputgoogle/type/datetime.proto:17:1:Package name "google.type" should be suffixed with a correctly formed version, such as "google.type.v1".
Scoop
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.