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
.proto files, and how
to handle imports.
buf.yamlconfig file below 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: "" deps:  build: roots: - . excludes:  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: Service breaking: use: - FILE
version key is required, and defines the current configuration version. The only accepted values are
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
deps 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: v1beta1 name: buf.build/acme/petapis deps: - 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
depsdon't need to include the
:<reference>suffix in most cases.
build key is optional, and is used to include and exclude specific Protobuf source files in the module defined
buf.yaml. Here is an example of all configuration options for
version: v1beta1 build: 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 are
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
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
protoc - that is,
these are the directories that the compiler uses to search for imports.
As an example, suppose your module defines two files,
proto/foo/baz/baz.proto. If you
want these files to refer to each other without the common
proto root, you would apply this configuration:
version: v1beta1 build: 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, see 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 essential to successful modern Protobuf development across a number of
1. Roots must not overlap, that is one root can not be a sub-directory of another root.
For example, this is not a valid configuration:
version: v1beta1 # THIS IS INVALID AND RESULTS IN A PRE-COMPILATION ERROR build: 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
foo/bar/bar.proto, it would be valid to import this file as either
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 this configuration:
version: v1beta1 build: roots: - foo - bar
Given the above configuration, it's invalid to have these two files:
This results in two files having the path
baz/baz.proto. Now add this file to the mix:
// THIS IS DEMONSTRATING SOMETHING BAD syntax = "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
-I flags given to
protoc. If the authors are being honest, we can't remember if it's the first
-I or second
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
files. For example,
grpc-gateway has its own
copy of the google.api definitions it needs. While
these are usually in sync, the
google.api schema can change. Imagine that we allowed this:
version: v1beta1 # THIS IS INVALID AND RESULTS IN A PRE-COMPILATION ERROR build: 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 Buf doesn't allow this.
lint key is optional, and specifies the
lint rules enforced on the files contained within the module. The
lint configuration shape is unchanged between
v1, so 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 refer to the
breaking configuration for more information.