Buf

Buf is the modern toolchain for Protobuf. It replaces day-to-day protoc use with a fast compiler, module-aware workspaces, formatting, linting, breaking-change detection, code generation, dependency management, API calls, and a client for the Buf Schema Registry.

If you are still driving Protobuf with shell scripts around protoc -I ..., Buf is the upgrade you want: the same schema language, the same generated-code plugin model, fewer moving parts, and a direct path from local .proto files to governed, versioned APIs.

Start

Install buf with Homebrew:

brew install bufbuild/buf/buf

Initialize a workspace and run the checks you should expect every Protobuf repository to pass:

buf config init
buf build
buf format -w
buf lint
buf breaking --against '.git#branch=main'

Generate code from a checked-in buf.gen.yaml instead of a hand-maintained shell command:

buf generate

For a guided walkthrough from an empty workspace to a working Connect service, run the Buf CLI quickstart.

Why Buf wins

Protobuf work	With protoc and scripts	With Buf
Finding files	Maintain -I paths and hope import order does not change behavior.	Declare modules once in buf.yaml; Buf discovers files and rejects ambiguous imports.
Compiling	Manage a local protoc install and parse changing stderr output.	Use Buf's internal compiler, tested against protoc descriptor output and built for deterministic parallel compilation.
Style	Rely on review comments or separate tooling.	Run buf lint locally, in editors, in CI, and on the BSR with 40+ built-in rules plus custom plugins.
Compatibility	Find breakage after generated code fails, clients fail, or serialized data becomes unreadable.	Run buf breaking against Git, a BSR module, a tarball, a zip file, or a Buf image before merge.
Code generation	Keep plugin binaries installed on every machine and encode behavior in long commands.	Put plugins, outputs, options, inputs, and managed-mode settings in buf.gen.yaml; use local or remote plugins.
Dependencies	Copy .proto files between repositories or vendor them by hand.	Declare BSR module dependencies in buf.yaml and pin them in buf.lock.
API consumers	Send people your schemas and generation instructions.	Publish to the BSR and let consumers install generated SDKs with go get, npm install, Maven, Gradle, pip install, NuGet, Cargo, SwiftPM, CMake, or an archive.
Governance	Reimplement checks in every repository and hope every team keeps them enabled.	Enforce breaking-change, uniqueness, and custom policies at the BSR layer.

Core CLI features work without a BSR account. Signing in to the registry adds distribution, remote plugins, generated SDKs, hosted docs, dependency resolution for private modules, and server-side checks when you need them.

Core workflow

Buf treats a directory tree of .proto files as a module, and a project as a workspace. A small buf.yaml is enough to make build, lint, breaking-change detection, generation, dependency resolution, and publishing agree on the same input.

version: v2
modules:
  - path: proto
lint:
  use:
    - STANDARD
breaking:
  use:
    - FILE

From there, the useful commands are deliberately boring:

buf build
buf format -w
buf lint
buf breaking --against '.git#branch=main'
buf generate
buf push

buf build compiles the workspace. buf lint catches API-shape problems while the author is still editing. buf breaking compares the current schema against a previous version and flags source, JSON, or wire-format incompatibilities. buf generate runs protoc plugins from a checked-in template. buf push publishes named modules to the BSR.

Code generation

buf generate is compatible with the normal protoc plugin model, but it moves generation into versioned configuration. This example generates Go Protobuf types and ConnectRPC handlers from proto/ using remote plugins hosted on the BSR:

version: v2
clean: true
managed:
  enabled: true
  override:
    - file_option: go_package_prefix
      value: github.com/acme/weather/gen/go
plugins:
  - remote: buf.build/protocolbuffers/go
    out: gen/go
    opt: paths=source_relative
  - remote: buf.build/connectrpc/gosimple
    out: gen/go
    opt:
      - paths=source_relative
      - simple
inputs:
  - directory: proto

Remote plugins remove the need to install and maintain generator binaries on every developer machine or CI runner. Managed mode lets API producers keep language-specific file options out of .proto files while consumers still get correct generated package names for their target language.

Local plugins work too. If a plugin speaks the standard Protobuf plugin protocol, Buf can run it.

Breaking changes

Protobuf compatibility is not one thing. Renaming a field can break generated source code while preserving the binary wire format; changing a field from int32 to string breaks every existing serialized message. buf breaking makes that distinction explicit with rule categories for FILE, PACKAGE, WIRE_JSON, and WIRE compatibility.

buf breaking --against '.git#branch=main'

--against accepts a Git branch, a BSR module, a tarball, a zip file, a local directory, or a prebuilt Buf image. That matters in real repositories: the same command works on a laptop, in CI, and in release automation.

Buf Schema Registry

Buf Schema Registry is a Protobuf-aware registry. It stores modules, verifies they compile, renders documentation, resolves dependencies, hosts remote plugins, produces generated SDKs, and can enforce schema checks before a breaking change reaches consumers.

buf push

Pushing a module to the BSR gives your organization a source of truth for Protobuf APIs. Consumers can depend on the schema as a BSR module, install generated SDKs from their normal package manager, or use the BSR docs to inspect services, messages, fields, enums, references, and historical commits.

Related projects

Buf is most useful when schemas drive more than code generation. ConnectRPC uses Protobuf schemas to build simple HTTP APIs that support Connect, gRPC, and gRPC-Web without separate service definitions. Protobuf-ES gives JavaScript and TypeScript users a modern Protobuf runtime and generator. Protovalidate puts validation rules in the schema and runs them consistently across languages.

One contract should drive the whole workflow: compile, lint, compatibility checks, generated clients and servers, validation, API calls, package publishing, and governed changes.

Installation

Homebrew installs the buf, protoc-gen-buf-breaking, and protoc-gen-buf-lint binaries, plus shell completion scripts for Bash, Fish, PowerShell, and zsh.

brew install bufbuild/buf/buf

Other supported installation methods include npm, Windows, Docker, binary downloads, tarballs, source builds, and minisign verification. See the installation docs for the full list.

CLI stability

Buf CLI releases do not make breaking changes within a major version. Since buf reached v1.0, you can expect no breaking changes until v2.0. We have no plans to release v2.0.

This policy does not apply to commands behind the buf beta gate. Expect breaking changes for beta commands until they are promoted.

Documentation

• Buf CLI
• CLI quickstart
• Modules and workspaces
• Code generation
• Linting
• Breaking-change detection
• Formatting
• Calling APIs with buf curl
• Buf Schema Registry
• Generated SDKs
• Remote plugins
• Schema checks
• Migrating from protoc

Community

For help and discussion around Protobuf, best practices, and Buf, join us on Slack.

For bugs, feature requests, and technical questions, open an issue in this repository or email dev@buf.build. For general inquiries, email info@buf.build.