The Buf logo

Buf

License Release CI Docker Homebrew Slack

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

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.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

Owner

PyPI data
Data sourced directly from PyPI's database.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.10

Tags

buf bufbuild protobuf protoc

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

buf_bin-1.72.0-py3-none-win_arm64.whl (14.6 MB view details)

Uploaded Python 3Windows ARM64

buf_bin-1.72.0-py3-none-win_amd64.whl (16.5 MB view details)

Uploaded Python 3Windows x86-64

buf_bin-1.72.0-py3-none-manylinux_2_17_riscv64.musllinux_1_2_riscv64.whl (14.8 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ riscv64musllinux: musl 1.2+ riscv64

buf_bin-1.72.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.musllinux_1_1_x86_64.whl (16.1 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64musllinux: musl 1.1+ x86-64

buf_bin-1.72.0-py3-none-manylinux2014_s390x.manylinux_2_17_s390x.musllinux_1_1_s390x.whl (15.5 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ s390xmusllinux: musl 1.1+ s390x

buf_bin-1.72.0-py3-none-manylinux2014_ppc64le.manylinux_2_17_ppc64le.musllinux_1_1_ppc64le.whl (14.3 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ppc64lemusllinux: musl 1.1+ ppc64le

buf_bin-1.72.0-py3-none-manylinux2014_armv7l.manylinux_2_17_armv7l.musllinux_1_1_armv7l.whl (14.7 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARMv7lmusllinux: musl 1.1+ ARMv7l

buf_bin-1.72.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.musllinux_1_1_aarch64.whl (14.6 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64musllinux: musl 1.1+ ARM64

buf_bin-1.72.0-py3-none-macosx_11_0_x86_64.whl (16.5 MB view details)

Uploaded Python 3macOS 11.0+ x86-64

buf_bin-1.72.0-py3-none-macosx_11_0_arm64.whl (15.4 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

File details

Details for the file buf_bin-1.72.0-py3-none-win_arm64.whl.

File metadata

  • Download URL: buf_bin-1.72.0-py3-none-win_arm64.whl
  • Upload date:
  • Size: 14.6 MB
  • Tags: Python 3, Windows ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for buf_bin-1.72.0-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 a92484e502e11ebd90b528eef5c09e21eeb1d83fffeb29edef284a3f76e04025
MD5 2d0577f283adf2c0a4eaf5ebe5f22e12
BLAKE2b-256 e7b4f7c85432667929de32fb340f2793267f3d242450586ac155b65237d67722

See more details on using hashes here.

Provenance

The following attestation bundles were made for buf_bin-1.72.0-py3-none-win_arm64.whl:

Publisher: pypi-publish.yaml on bufbuild/buf-pypi-publish

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file buf_bin-1.72.0-py3-none-win_amd64.whl.

File metadata

  • Download URL: buf_bin-1.72.0-py3-none-win_amd64.whl
  • Upload date:
  • Size: 16.5 MB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for buf_bin-1.72.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 21939478a4db814d4465fc09123f6a44e62e546a3f18c025c5744741238e7021
MD5 dd3a3ae44ac053f405c4241616c49a63
BLAKE2b-256 872a4d0d8b4289e11f48867c913d419ca0ddccec9a0ac48e483a549b948daebd

See more details on using hashes here.

Provenance

The following attestation bundles were made for buf_bin-1.72.0-py3-none-win_amd64.whl:

Publisher: pypi-publish.yaml on bufbuild/buf-pypi-publish

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file buf_bin-1.72.0-py3-none-manylinux_2_17_riscv64.musllinux_1_2_riscv64.whl.

File metadata

File hashes

Hashes for buf_bin-1.72.0-py3-none-manylinux_2_17_riscv64.musllinux_1_2_riscv64.whl
Algorithm Hash digest
SHA256 879e29b073d976fc21ea3e2464fceca904f92cb5ce4b7bbaf2b56e8ab5a090b1
MD5 81fd7d8919ae721cf1d36d1503d36cda
BLAKE2b-256 1eb901d8d60211a0b27e2199d0c50bc265d750c55237708df1f3fb0d4929f1a1

See more details on using hashes here.

Provenance

The following attestation bundles were made for buf_bin-1.72.0-py3-none-manylinux_2_17_riscv64.musllinux_1_2_riscv64.whl:

Publisher: pypi-publish.yaml on bufbuild/buf-pypi-publish

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file buf_bin-1.72.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.musllinux_1_1_x86_64.whl.

File metadata

File hashes

Hashes for buf_bin-1.72.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.musllinux_1_1_x86_64.whl
Algorithm Hash digest
SHA256 01573bdff85d11b905f431dc707e954e4ecc408bb65983d1b6f77098b112151f
MD5 636c88db67fab4578c41eb678a0625c7
BLAKE2b-256 d4d1d54430879c503643e3b5ca8b9ed6072b006ad263babd95fc9bfdf0e1a2bf

See more details on using hashes here.

Provenance

The following attestation bundles were made for buf_bin-1.72.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.musllinux_1_1_x86_64.whl:

Publisher: pypi-publish.yaml on bufbuild/buf-pypi-publish

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file buf_bin-1.72.0-py3-none-manylinux2014_s390x.manylinux_2_17_s390x.musllinux_1_1_s390x.whl.

File metadata

File hashes

Hashes for buf_bin-1.72.0-py3-none-manylinux2014_s390x.manylinux_2_17_s390x.musllinux_1_1_s390x.whl
Algorithm Hash digest
SHA256 f8f077ffc21b8eb47b63e001988fdb3f638cb62431ec3d6b9d40ba826ec5761c
MD5 761f77ff18313ed962af4762bf0d8af7
BLAKE2b-256 36ec3bff6981672c1a5a2b4ceb51e82a252d3521c83c95a3426a4de25a3c3dad

See more details on using hashes here.

Provenance

The following attestation bundles were made for buf_bin-1.72.0-py3-none-manylinux2014_s390x.manylinux_2_17_s390x.musllinux_1_1_s390x.whl:

Publisher: pypi-publish.yaml on bufbuild/buf-pypi-publish

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file buf_bin-1.72.0-py3-none-manylinux2014_ppc64le.manylinux_2_17_ppc64le.musllinux_1_1_ppc64le.whl.

File metadata

File hashes

Hashes for buf_bin-1.72.0-py3-none-manylinux2014_ppc64le.manylinux_2_17_ppc64le.musllinux_1_1_ppc64le.whl
Algorithm Hash digest
SHA256 1563276ff0c35addd796c674e8a84f95f88a3fa567f3329ecdd7ffec35efea93
MD5 ea5b93eb1b9a7ce992b930b3a77757da
BLAKE2b-256 81697a8a68c9b1155b5611415ca745b27c2b00332a970b14fd881d681e93b948

See more details on using hashes here.

Provenance

The following attestation bundles were made for buf_bin-1.72.0-py3-none-manylinux2014_ppc64le.manylinux_2_17_ppc64le.musllinux_1_1_ppc64le.whl:

Publisher: pypi-publish.yaml on bufbuild/buf-pypi-publish

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file buf_bin-1.72.0-py3-none-manylinux2014_armv7l.manylinux_2_17_armv7l.musllinux_1_1_armv7l.whl.

File metadata

File hashes

Hashes for buf_bin-1.72.0-py3-none-manylinux2014_armv7l.manylinux_2_17_armv7l.musllinux_1_1_armv7l.whl
Algorithm Hash digest
SHA256 faf906ca80efea5e16024d816f3edb4dbc0006bc5ac77dbe9b0cc2987d58cee7
MD5 04dccc4af2062dd71db0a0e977253e36
BLAKE2b-256 4a92ece9420f79ea0bc3803e659c7633f3c5795e850f32721c88bc8d937bcf8f

See more details on using hashes here.

Provenance

The following attestation bundles were made for buf_bin-1.72.0-py3-none-manylinux2014_armv7l.manylinux_2_17_armv7l.musllinux_1_1_armv7l.whl:

Publisher: pypi-publish.yaml on bufbuild/buf-pypi-publish

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file buf_bin-1.72.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.musllinux_1_1_aarch64.whl.

File metadata

File hashes

Hashes for buf_bin-1.72.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.musllinux_1_1_aarch64.whl
Algorithm Hash digest
SHA256 79e9e0622e7b61a11b7267e33ac5e3bc9862eb45fe73098b74f961d1d398c467
MD5 2623c129b9255138f2902ee738d0f25c
BLAKE2b-256 0d7df98609c72149f8f47408d887f265a30c4bfa030af97b2d160fabc401b61a

See more details on using hashes here.

Provenance

The following attestation bundles were made for buf_bin-1.72.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.musllinux_1_1_aarch64.whl:

Publisher: pypi-publish.yaml on bufbuild/buf-pypi-publish

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file buf_bin-1.72.0-py3-none-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for buf_bin-1.72.0-py3-none-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 c3cb5720e8905290b0d08ad49b4f57f73b8e1f19c85cad7f7746ecfc2fb3fd06
MD5 25cd0d0c82a8bdd112cea269c8390a21
BLAKE2b-256 a8e03dc0dd9c98ab862236171fd2799bec0eb955b076eeb5c1345a474ff317d3

See more details on using hashes here.

Provenance

The following attestation bundles were made for buf_bin-1.72.0-py3-none-macosx_11_0_x86_64.whl:

Publisher: pypi-publish.yaml on bufbuild/buf-pypi-publish

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file buf_bin-1.72.0-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for buf_bin-1.72.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 80b91a34c1bde6103909522423692fd174add77be14f9549c90d0331ac22f041
MD5 faf94445efe4c8825dd82cd9de7034e8
BLAKE2b-256 d94d4b305995cc79c08abfff452b97df4f78c0bf22e54b55d30c9e3ff3e3e6a8

See more details on using hashes here.

Provenance

The following attestation bundles were made for buf_bin-1.72.0-py3-none-macosx_11_0_arm64.whl:

Publisher: pypi-publish.yaml on bufbuild/buf-pypi-publish

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.72.0 This release

10 files

1.71.0

10 files

1.70.0

10 files

1.69.0

10 files

1.68.4

10 files

1.68.3

10 files

1.68.2

10 files

1.68.1

10 files

1.68.0

10 files

1.67.0

10 files

1.66.1

10 files

1.66.0

10 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page