Skip to content

Remote plugins#

A remote plugin is a Protobuf code-generation plugin (the protoc-gen-* binaries you’d otherwise install locally) hosted on the BSR. Reference one in buf.gen.yaml, run buf generate, and the BSR sends the input to its plugin executor, runs the plugin against it, and writes the output to your local disk:

buf.gen.yaml
version: v2
plugins:
  - remote: buf.build/protocolbuffers/go:v1.36.11
    out: gen/go
    opt: paths=source_relative
  - remote: buf.build/grpc/go:v1.5.1
    out: gen/go
    opt: paths=source_relative

Remote vs. local plugins#

Remote plugins replace local plugin installation with a published, version-pinned reference and execution on the BSR. That makes code generation reproducible across laptops and CI without asking every repository to install and update the same plugin binaries. The trade-offs:

  • Remote plugins require the plugin to be published (Buf-managed, community-managed, or as a custom plugin on a private BSR instance), and run under the BSR sandbox’s filesystem and network constraints.
  • Local plugins work with anything protoc-gen-* you have on $PATH, including private binaries you can’t publish, and run on your own machine, so they can do things the BSR sandbox prohibits.

buf.gen.yaml accepts both kinds of plugins in the same file; pick remote where it fits and fall back to local where you need to.

If your consumers don’t need generated files checked into their repositories, use generated SDKs instead: the BSR generates the package and consumers install it with their normal package manager.

Browse the catalog#

The plugin catalog at buf.build/plugins lists every public plugin on the public BSR; private BSR instances expose their own catalogs at the equivalent URL on the instance host. Filter by ecosystem or language to find candidates:

Remote plugin browse screen with language filters

Open a plugin to copy a ready-made buf.gen.yaml entry, along with any installation instructions for the runtime libraries the generated code expects:

Plugin detail page with copy-paste buf.gen.yaml entry for Go

Use the version dropdown to pin a specific version; remove the version suffix to track the latest.

The catalog is a mix of Buf-curated plugins and community-contributed plugins, consolidated under one managed surface; every plugin in the catalog is treated identically by the BSR’s plugin executor.

Reference a remote plugin in buf.gen.yaml#

Paste the catalog snippet into the plugins list of your buf.gen.yaml:

buf.gen.yaml
version: v2
plugins:
  - remote: buf.build/protocolbuffers/go:v1.36.11
    out: gen/go
    opt: paths=source_relative
  - remote: buf.build/grpc/go:v1.5.1
    out: gen/go
    opt: paths=source_relative

Pin a plugin version (:vX.Y.Z) for reproducible builds; an unpinned reference resolves to the latest version every time buf generate runs and can introduce unexpected changes.

For combination patterns (gRPC and Connect plugins that need to run alongside protocolbuffers/go, for example) and the rest of the configuration surface, see Generate code with remote plugins and the buf.gen.yaml reference.

Request or contribute a plugin#

To request a Buf-maintained plugin in the public catalog, open an issue on the bufbuild/plugins repository.

To publish your own plugin on a private BSR instance (public to the instance or scoped to one organization), see Custom plugins.