Skip to main content


Buf provides stub generation capability using it's high-performance, internal compiler via buf generate.

buf generate uses a template file of the following shape:

# The version of the generation template.
# Required.
# The only currently-valid value is v1beta1.
version: v1beta1
# The plugins to run.
# The name of the plugin.
# Required.
# By default, buf generate will look for a binary named protoc-gen-NAME on your $PATH.
- name: go
# The the relative output directory.
# Required.
out: gen/go
# Any options to provide to the plugin.
# Optional.
# Can be either a single string or list of strings.
opt: paths=source_relative
# The custom path to the plugin binary, if not protoc-gen-NAME on your $PATH.
path: custom-gen-go # optional
# The generation strategy to use. There are two options:
# 1. "directory"
# This will result in buf splitting the input files by directory, and making separate plugin
# invocations in parallel. This is roughly the concurrent equivalent of:
# for dir in $(find . -name '*.proto' -print0 | xargs -0 -n1 dirname | sort | uniq); do
# protoc -I . $(find "${dir}" -name '*.proto')
# done
# Almost every Protobuf plugin either requires this, or works with this,
# and this is the recommended and default value.
# 2. "all"
# This will result in buf making a single plugin invocation with all input files.
# This is roughly the equivalent of:
# protoc -I . $(find . -name '*.proto')
# This is needed for certain plugins that expect all files to be given at once.
# Optional. If omitted, "directory" is used. Most users should not need to set this option.
strategy: directory
- name: java
out: gen/java

As an example, here's a typical buf.gen.yaml for go and grpc, assuming protoc-gen-go and protoc-gen-go-grpc are on your $PATH:

version: v1beta1
- name: go
out: gen/go
opt: paths=source_relative
- name: go-grpc
out: gen/go
opt: paths=source_relative,require_unimplemented_servers=false

By default, buf generate will look for a file of this shape named buf.gen.yaml in your current directory. This can be thought of as a template for the set of plugins you want to invoke.

The first argument is the source, module, or image to generate from. If no argument is specified, defaults to ".".

Call with:

# uses buf.gen.yaml as template, current directory as input
$ buf generate
# same as the defaults (template of "buf.gen.yaml", current directory as input)
$ buf generate --template buf.gen.yaml .
# --template also takes YAML or JSON data as input, so it can be used without a file
$ buf generate --template '{"version":"v1beta1","plugins":[{"name":"go","out":"gen/go"}]}'
# download the repository, compile it, and generate per the bar.yaml template
$ buf generate --template bar.yaml
# generate to the bar/ directory, prepending bar/ to the out directives in the template
$ buf generate --template bar.yaml -o bar

The paths in the template and the -o flag will be interpreted as relative to your current directory, so you can place your template files anywhere.

If you only want to generate stubs for a subset of your input, you can do so via the --path flag:

# Only generate for the files in the directories proto/foo and proto/bar
$ buf generate --path proto/foo --path proto/bar
# Only generate for the files proto/foo/foo.proto and proto/foo/bar.proto
$ buf generate --path proto/foo/foo.proto --path proto/foo/bar.proto
# Only generate for the files in the directory proto/foo on your GitHub repository
$ buf generate --template buf.gen.yaml --path proto/foo

Note that all paths must be contained within a root. For example, if you have the single root proto, you cannot specify --path proto, however --path proto/foo is allowed as proto/foo is contained within proto.

Plugins are invoked in the order they are specified in the template, but each plugin has a per-directory parallel invocation, with results from each invocation combined before writing the result. This is equivalent behavior to buf protoc --by_dir.