buf.yaml file defines a module, and is placed at the root of the Protobuf source files
it defines. The placement of the
buf.yaml configuration tells
buf where to search for
and how to handle imports.
buf.yaml file demonstrates all default values being explicitly set, this file is the equivalent of no options being set in your
buf.yaml at all.
version: v1beta1# name and deps default to empty#name:#deps:lint: use: - DEFAULT enum_zero_value_suffix: _UNSPECIFIED rpc_allow_same_request_response: false rpc_allow_google_protobuf_empty_requests: false rpc_allow_google_protobuf_empty_responses: false service_suffix: Servicebreaking: use: - FILE
version key is required, and defines the current configuration version. The only accepted
name is optional, and uniquely identifies your module. The
name must be a valid module name
and is directly associated with the repository that owns it.
deps key is optional, and declares one or more modules that your module depends on. Each
entry must be a module reference, and, is directly associated with a repository, as well as a
reference, which is either a tag or commit. A complete example of
deps format is shown below:
version: v1beta1name: buf.build/acme/petapisdeps: - buf.build/acme/paymentapis # The latest commit. - buf.build/acme/pkg:47b927cbb41c4fdea1292bafadb8976f # The '47b927cbb41c4fdea1292bafadb8976f' commit. - buf.build/googleapis/googleapis:v1beta1.1.0 # The 'v1beta1.1.0' tag.
Depending on specific references is an advanced feature; you should depend on the latest commit whenever possible. In other words, your
depswill not need to include the
:<reference>suffix in most cases. Please refer to
buf's best practices to learn more!
build key is optional, and is used to include and exclude specific Protobuf source files in the
module defined by the
buf.yaml. The following is an example of all configuration options for
version: v1beta1build: roots: - proto - vendor/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis excludes: - proto/foo/bar
This is a list of the directories to ignore from
.proto file discovery. Any directories added
to this list will be completely skipped and not included in the module. We do not recommend
using this option in general, however in some situations it is unavoidable.
This is a list of the directories that contain your
.proto files. The directory paths must be relative
to the root of your
buf.yaml, and cannot point to a location outside of your
buf.yaml. They also represent
the root of your import paths within your
For those familiar with
roots corresponds to your
--proto_paths, aliased as
that is, these are the directories that the compiler uses to search for imports.
As an example, suppose your module defines two files,
If you want these files to refer to each other without the common
proto root, you would configure the following.
version: v1beta1build: roots: - proto
baz.proto wants to import
bar.proto, it does so relative to
syntax = "proto3"; package foo.baz; import "foo/bar/bar.proto";
These requirements are no longer relevant in
rootshave been removed. These guidelines remain for users that are still using
v1beta1. For more information, please refer to the migration guide.
There are two additional requirements that
buf imposes on your
.proto file structure for compilation to succeed that
are not enforced by
protoc, both of which are very important for successful modern Protobuf development across a number
1. Roots must not overlap, that is one root can not be a sub-directory of another root.
For example, the following is not a valid configuration:
version: v1beta1# THIS IS INVALID AND WILL RESULT IN A PRE-COMPILATION ERRORbuild: roots: - foo - foo/bar
This is important to make sure that across all your
.proto files, imports are consistent In the above example, for a given
foo/bar/bar.proto, it would be valid to import this file as either
bar.proto. Having inconsistent
imports leads to a number of major issues across the Protobuf plugin ecosystem.
.proto file paths must be unique relative to the roots.
For example, consider the following configuration:
version: v1beta1build: roots: - foo - bar
Given the above configuration, it is invalid to have the following two files:
This results in two files having the path
baz/baz.proto. Given the following third file
// THIS IS DEMONSTRATING SOMETHING BADsyntax = "proto3"; package bar.baz; import "baz/baz.proto";
Which file is being imported? Is it
bar/baz/baz.proto? The answer depends on the order of the
flags given to
protoc. If the authors are being honest, we can't remember if it's the first
-I or second
-I that wins -
we have outlawed this in our own builds for a long time.
While the above example is relatively contrived, the common error that comes up is when you have vendored
For example, grpc-gateway has it's
own copy of the google.api definitions it needs. While these
are usually in sync, the
google.api schema can change. If we allowed the following:
version: v1beta1# THIS IS INVALID AND WILL RESULT IN A PRE-COMPILATION ERRORbuild: roots: - proto - vendor/github.com/googleapis/googleapis - vendor/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis
Which copy of
google/api/*.proto wins? The answer is no one wins, so this is not allowed.
lint key is optional, and specifies the
lint rules enforced on the files contained within the
lint configuration shape is unchanged between
v1, so please refer
to the lint configuration for more information.
breaking key is optional, and specifies the breaking change detection rules enforced on the files
contained within the module. The
breaking configuration shape is unchanged between
v1, so please refer to the breaking configuration for more information.