Skip to main content

Installation

CI example#

An example is available at bufbuild/buf-example that:

  • Installs buf from GitHub Releases.
  • Runs linting and breaking change detection.

CI is set up for:

Within this example are the following main targets:

  • make local runs linting, and then breaking change detection against your local git repository. This is useful for development.
  • make remote runs linting, and then breaking change detection against your remote git repository. This is useful because most CI providers only clone the branch under test and to a certain depth.

Note that GitHub Actions makes it possible to use make local by cloning the branch you want, creating a local head for it, and then cloning the commit under test. See ci.yaml for an example.

Via Homebrew#

Buf can be installed for Mac or Linux using Homebrew via the bufbuild/homebrew-buf tap.

brew tap bufbuild/buf
brew install buf

This will install:

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

Via GitHub Releases#

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 that is needed to get started.

To install just the buf, protoc-gen-buf-breaking, or protoc-gen-buf-lint binaries to to /usr/local/bin for version 0.48.2:

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

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

To uninstall from /usr/local/bin:

# Substitute BIN for your bin directory.
# Substitute BINARY_NAME for "buf", "protoc-gen-buf-breaking", or "protoc-gen-buf-lint".
BIN="/usr/local/bin" && \
BINARY_NAME="buf" && \
rm -f "${BIN}/${BINARY_NAME}"

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 0.48.2:

# Substitute PREFIX for your install prefix.
# Substitute VERSION for the current released version.
PREFIX="/usr/local" && \
VERSION="0.48.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 will be 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"

From Source#

The binaries can be installed from source if Golang 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 get \
github.com/bufbuild/buf/cmd/buf \
github.com/bufbuild/buf/cmd/protoc-gen-buf-breaking \
github.com/bufbuild/buf/cmd/protoc-gen-buf-lint

Future Windows Support#

Windows support is not yet available, however will be released in the future. Buf is designed from the ground up to be OS and platform independent, however we have not yet set up the requisite testing required to be comfortable releasing Windows assets. If this is something you are interested in, please contact us.