Skip to content

Generating code#

buf generate runs Protobuf plugins over your .proto files, producing source code in whatever language the plugins target: Go, TypeScript, Java, Python, C++, Rust, and so on. It reads a buf.gen.yaml file that lists the plugins to run and where to put their output, then runs them. A typical config and invocation looks like this:

buf.gen.yaml
version: v2
plugins:
  - remote: buf.build/protocolbuffers/go
    out: gen/go
  - remote: buf.build/connectrpc/go
    out: gen/go

$ buf generate

That run produces Go structs, enums, and Connect service stubs under gen/go, compiled from whatever .proto files the current workspace contains.

See the code generation quickstart for a hands-on walk-through.

How it compares to protoc#

If you’ve used protoc, you know the setup: flag-heavy command lines, plugins installed by hand on every developer’s machine, and shell scripts trying to tie the whole thing together reproducibly. buf generate handles the same job with fewer moving parts:

  • Everything lives in buf.gen.yaml instead of on the command line. Check the file in, and every developer and CI run produces the same output.
  • Plugins don’t need to be installed locally. The BSR hosts remote plugins pinned by version, so builds are reproducible without a separate install step.
  • Input isn’t limited to local .proto files. buf generate accepts modules on the BSR, Git repositories, tarballs, and other input types.
  • Compilation uses every available core via Buf’s internal compiler, usually about 2x faster than protoc on a non-trivial workspace.

Key concepts#

buf.gen.yaml
Configuration for code generation. Lists the plugins to run, where each one writes its output, and any options passed along. See the full reference.
plugins
External programs that implement the Protobuf plugin interface. A plugin reads a compiled schema on stdin and writes generated source files on stdout. Buf supports local plugins (installed on your machine, like protoc-gen-go), remote plugins (hosted on the BSR and fetched automatically), and the built-in plugins from protoc itself.
input
What buf generate reads from. Normally that’s a local workspace, but the command also accepts BSR module references, Git repository URLs, tarballs, and other formats. See Inputs for the full list.

Local plugins#

Local plugins work much the way they do under protoc, but configured in buf.gen.yaml instead of on the command line. Use plugins.local for an executable installed on your $PATH:

buf.gen.yaml
version: v2
plugins:
  - local: protoc-gen-go
    out: gen/go

Built-in protoc plugins (cpp, java, python, etc.) are referenced with plugins.protoc_builtin instead:

buf.gen.yaml
version: v2
plugins:
  - protoc_builtin: cpp
    out: gen/cpp

Remote plugins#

Remote plugins are the same plugins you’d install locally, but fetched from the BSR and run automatically. No local install step, and the plugin version is pinned in your config, so everyone on the team runs the same version:

buf.gen.yaml
version: v2
plugins:
  - remote: buf.build/protocolbuffers/go
    out: gen/go
  - remote: buf.build/bufbuild/es
    out: gen/ts

See Remote plugins for the full catalog and version-pinning syntax.

Managed mode#

Managed mode moves language-specific options like go_package, java_package, or csharp_namespace out of your .proto files and into buf.gen.yaml. Your schema stays language-neutral, and each consumer can generate code their own way without editing the source files.

Turn it on with a one-line block:

buf.gen.yaml
version: v2
managed:
  enabled: true
plugins:
  - remote: buf.build/protocolbuffers/go
    out: gen/go

See Managed mode for the defaults, per-option overrides, and the motivation behind it.

Generated SDKs#

If a module is already published to the BSR, consumers usually don’t need to run buf generate themselves. The BSR produces generated SDKs for every published module in every supported language and serves them through each language’s native package manager: go get, npm install, cargo add, mvn, pip, dotnet add. Pull the SDK in like any other dependency.

Generated SDKs are usually the right answer when you’re consuming a schema someone else publishes rather than building and publishing your own.

Further reading#