buf.gen.yaml v1 config file#

Note

This page documents an older version of this Buf config file—for new projects, you should use v2 files. See the v2 buf.gen.yaml reference and the migration guide for details about the current configuration and migration instructions.

buf.gen.yaml is a configuration file used by the buf generate command to generate integration code for the languages of your choice. This file is most often used with a module (but can be used with other input types), and is typically placed next to your buf.work.yaml file at the root of your Protobuf files:

.
├── buf.gen.yaml
├── buf.work.yaml
├── proto
│   └── location
│           └── location.proto
│   └── weather
│           └── weather.proto
├── buf.lock
└── buf.yaml

`version`#

Required. Defines the current configuration version. Accepted values are v1beta1 and v1.

`plugins`#

Required. Each entry in the plugins key is a protoc plugin configuration. Plugins are invoked in parallel and their outputs are written in the order you specify here.

`plugin`#

Required. The name of the plugin to use—can be local or remote.

Local plugins: If using a protoc plugin, the protoc-gen- prefix is assumed and you should omit it (for example, go instead of protoc-gen-go). By default, the Buf CLI expects a protoc-gen-<name> program to be on your PATH so that it can be discovered and executed. This can be overridden with the path field below.
Remote plugins: Specify the path to the plugin on the Buf Schema Registry (BSR).
- For all public BSR plugins, this takes the form: buf.build/<owner-org>/<plugin-name>:<plugin-version>
- For custom plugins, this takes the form: <bsr-server>/<owner-org>/<plugin-name>:<plugin-version>
- <plugin-version> is optional. If it isn't present, the latest version is used. If it's specified, the revision field can be specified to pin an exact version.
  - The plugin version is specified by the upstream project.
  - The revision is a sequence number that Buf increments when rebuilding or repackaging the plugin.
  If you don't specify a plugin version, the latest version is pulled in. To avoid unexpected updates and possible breaking changes, pin to a specific version.

`out`#

Required. Controls where the generated files are deposited for a given plugin. Although absolute paths are supported, this configuration is typically a relative output directory to where buf generate is run.

`opt`#

Optional. Specifies one or more plugin options for each plugin independently. You can provide options as either a single string or a list of strings.

`path`#

Optional. Only works with local plugins. Overrides the default location and explicitly specifies where to locate the plugin. For example, if a custom plugin called protoc-gen-foo isn't located on your PATH, but is found at bin/proto/protoc-gen-foo, you can refer to it like this:

path: bin/proto/protoc-gen-foo

The path can include some arguments. If it has more than one element, the first should be the plugin binary and the others are optional arguments to pass to the binary. For example, you can run the version of protoc-gen-go that matches the google.golang.org/protobuf specified by go.mod by:

path: ["go", "run", "google.golang.org/protobuf/cmd/protoc-gen-go"]

`revision`#

Optional. May be used along with the plugin field to pin an exact version of a remote plugin. In most cases, we recommend omitting revision, in which case the latest revision of that version of the plugin is used (automatically pulling in the latest bug fixes). Example:

- plugin: buf.build/protocolbuffers/go:v1.28.1
  revision: 1

`strategy`#

Optional. Specifies the invocation strategy to use. There are two options:

directory (default for local plugins): This results in buf splitting the input files by directory and making separate plugin invocations in parallel, roughly the concurrent equivalent of this operation:
```
$ for dir in $(find . -name '*.proto' -print0 | xargs -0 -n1 dirname | sort | uniq); do protoc -I . $(find "${dir}" -name '*.proto'); done
```
Almost every protoc plugin requires this, so it's the recommended setting for local generation.
all: This results in buf generate making a single plugin invocation with all input files, which is roughly equivalent to this:
```
$ protoc -I . $(find . -name '*.proto')
```
This option is needed for certain plugins that expect all files to be given at once. The BSR also sets the value to all for remote plugin generation to improve performance.

`protoc_path`#

Optional. Only applies to the code generators that are built in to protoc. Normally, a plugin is a separate executable with a binary name like protoc-gen-<name>. But for a handful of plugins, the executable used is protoc itself. The following plugins result in invoking protoc instead of a dedicated plugin binary:

cpp
csharp
java
js (before v21)
kotlin (after v3.17)
objc
php
pyi
python
ruby

Normally for the above plugins, the Buf CLI executes the protoc binary that's found in your $PATH, but this configuration option lets you point to a specific binary. It's particularly useful if you need to support a specific version of protoc, which could differ from the version in $PATH. For example:

protoc_path: /path/to/specific/version/bin/protoc

It can also be used to supply additional arguments to protoc, by setting this value to an array of strings, where the first array element is the path. For example:

protoc_path:
    - /path/to/specific/version/bin/protoc
    - --experimental_editions

`managed`#

The managed key is used to configure managed mode, an advanced feature for Protobuf options (see Managed mode for more details).

Managed mode example—buf.gen.yaml

version: v1
managed:
    enabled: true
    optimize_for: CODE_SIZE
    go_package_prefix:
        default: github.com/acme/weather/private/gen/proto/go
        except:
            - buf.build/googleapis/googleapis
        override:
            buf.build/acme/weather: github.com/acme/weather/gen/proto/go
    override:
        JAVA_PACKAGE:
            acme/weather/v1/weather.proto: "org"

The definitions below refer to the following two sample .proto files.

proto/location/location.proto

syntax = "proto3";

package ac_me.location;

message Location {
  float latitude = 1;
  float longitude = 2;
}

proto/weather/weather.proto

syntax = "proto3";

package ac_me.weather;

import "location/location.proto";

message CurrentWeatherRequest {
  location.Location location = 1;
}

message CurrentWeatherResponse {
  float temperature = 1;
  string detail = 2;
}

service WeatherVisionService {
  rpc CurrentWeather(CurrentWeatherRequest) returns (CurrentWeatherResponse);
}

`enabled`#

Required if any other managed keys are set. Setting enabled equal to true with no other keys set enables managed mode according to default behavior.

`cc_enable_arenas`#

Optional. If unset, this option is left as specified in your .proto files. As of Protocol Buffers release v3.14.0, changing this value no longer has any effect.

`csharp_namespace`#

Optional. Controls the default C# namespace for classes generated from all of the .proto files contained within the input. Managed mode generates C# files with a top-level namespace based on each .proto file’s package, with each part transformed to PascalCase. The default can't be set differently, but can be overridden or excepted for specific .proto files.

For example, weather.proto defines its package as package ac_me.weather;, which in the generated C# code becomes namespace AcMe.Weather. See the default behavior section for details.

This namespace doesn't affect the directory structure of the generated file.

`except`#

Optional. Removes the specified modules from the default csharp_namespace option behavior. The except keys must be valid module names.

`override`#

Optional. Overrides the csharp_namespace value used for specific modules. The override keys must be valid module names.

`go_package_prefix`#

Optional. Controls what the go_package value is set to for all of the .proto files contained within the input. If unset, this option is left as specified in your .proto files.

`default`#

Required if the go_package_prefix key is set. The default value is used as a prefix for the go_package value set in each of the files. It must be a relative file path that must not jump context from the current directory—it must be subdirectories relative to the current working directory. As an example, ../external is invalid. In the configuration example, the github.com/acme/weather/gen/proto/go prefix is joined with the given Protobuf file's relative path from the module root. The acme/weather/v1/weather.proto file then has this go_package set:

acme/weather/v1/weather.proto

syntax = "proto3";
package acme.weather.v1;
option go_package = "github.com/acme/weather/gen/proto/go/acme/weather/v1;weatherv1";`

If the Protobuf file's package declaration conforms to the PACKAGE_VERSION_SUFFIX lint rule, the final two path elements are concatenated and included after the ; element in the go_package result. The above example generates a Go package with a package declaration equal to weatherv1, which enables you to import Go definitions from a variety of generated packages that otherwise collide (a lot of Protobuf packages contain the v1 suffix).

`except`#

Optional. Removes certain modules from the go_package option behavior. The except values must be valid module names. There are situations where you may want to enable managed mode for the go_package option in most of your Protobuf files, but not necessarily for all of your Protobuf files. This is particularly relevant for the buf.build/googleapis/googleapis module, which points its go_package value to an external repository. Popular libraries such as grpc-go depend on these go_package values, so it's important that managed mode does not overwrite them.

`override`#

Optional. Overrides the go_package file option value used for specific modules. The override keys must be valid module names. Additionally, the corresponding override values must be a valid Go import path and must not jump context from the current directory. As an example, ../external is invalid. This setting is used for workspace environments, where you have a module that imports from another module in the same workspace, and you need to generate the Go code for each module in different directories. This is particularly relevant for repositories that decouple their private API definitions from their public API definitions.

`java_multiple_files`#

Optional. Controls what the java_multiple_files value is set to for all of the .proto files contained within the input. The only accepted values are false and true. Managed mode defaults to true (Protobuf's default is false).

When set to true, managed mode generates one or more Java files for each top level message or enum, but not services. These types won't be nested inside the wrapper class defined by java_outer_classname. For example:
- CurrentWeatherRequest.java
- CurrentWeatherRequestOrBuilder.java
- CurrentWeatherResponse.java
- CurrentWeatherResponseOrBuilder.java
- WeatherProto.java
When set to false, only Weather.java is generated for weather.proto.

`java_outer_classname`#

This option can't be specified. It can only be overridden using the per-file override.

When managed mode is enabled, java_outer_classname is set to the PascalCase-equivalent of the file's name, removing the .from the.protoextension. This converts the weather.proto filename, for example, to WeatherProto.

buf.gen.yaml override example

version: v1
managed:
    enabled: true
    override:
        JAVA_OUTER_CLASSNAME:
            acme/weather/v1/weather.proto: "WeatherProtov1"

`java_package_prefix`#

Optional. Controls what's prepended to the java_package value is set to for all of the .proto files contained within the input. If this is unset, managed mode's default value is com.

`default`#

Required if the java_package_prefix key is set. The default value is used as a prefix for the java_package value set in each of the files.

`except`#

Optional. Removes the specified modules from the java_package option behavior. The except keys must be valid module names.

`override`#

Optional. Overrides the java_package option value used for specific modules. The override keys must be valid module names.

`java_string_check_utf8`#

Optional. Controls what the java_string_check_utf8 value is set to for all of the .proto files contained within the input. The only accepted values are false and true. If unset, this option is left as specified in your .proto files. Protobuf's default is false.

`objc_class_prefix`#

Optional. When managed mode is enabled, this defaults to an abbreviation of the package name as described in the default behavior section. The value is prepended to all generated classes.

`default`#

Optional. Overrides managed mode's default value for the class prefix.

`except`#

Optional. Removes the specified modules from the objc_class_prefix option behavior. The except keys must be valid module names.

`override`#

Optional. Overrides any default objc_class_prefix option value for specific modules. The override keys must be valid module names.

`optimize_for`#

Optional. Controls what the optimize_for value is set to for all of the .proto files contained within the input. The only accepted values are SPEED, CODE_SIZE and LITE_RUNTIME. Managed mode won't modify this option if unset.

Value	Description
SPEED	Generate highly optimized code for parsing, serializing, and performing common operations on messages
CODE_SIZE	Generate minimal classes and instead rely on shared, reflection-based code for serialization, parsing, and other operations
LITE_RUNTIME	Generate classes that depend only on the “lite” Protobuf runtime

`php_metadata_namespace`#

This option can't be specified. It can only be overridden using the per-file override.

When managed mode is enabled, php_metadata_namespace defaults to the default managed mode php_namespace value with \GPBMetadata appended to it. For example, acme.weather.foo_bar.v1 becomes Acme\Weather\FooBar\V1\GPBMetadata.

buf.gen.yaml override example

version: v1
managed:
  enabled: true
  override:
    PHP_METADATA_NAMESPACE:
      acme/weather/v1/weather.proto: "Acme\Weather\FooBar\GPBMetadata"

`php_namespace`#

This option can't be specified. It can only be overridden using the per-file override.

When managed mode is enabled, php_namespace defaults to the package name connected by \ with each part in PascalCase. If part of the name is a reserved keyword, it appends _ at the end of that part. For example:

acme.weather.foo_bar.v1 becomes Acme\Weather\FooBar\V1
acme.error.v1 becomes Acme\Error_\V1

buf.gen.yaml override example

version: v1
managed:
  enabled: true
  override:
    PHP_NAMESPACE:
      acme/weather/v1/weather.proto: "Acme\Weather\FooBar"

`ruby_package`#

Optional. Controls what the ruby_package value is set to for all of the .proto files contained within the input. Managed mode's default value is the package name with each package sub-name capitalized, with :: substituted for .. For example, acme.weather.v1 becomes Acme::Weather::V1. The default can't be set differently, but can be overridden or excepted for specific .proto files.

`except`#

Optional. Removes the specified modules from the ruby_package file option override behavior. The except keys must be valid module names.

`override`#

Optional. Overrides the ruby_package file option value used for specific modules. The override keys must be valid module names.

`override`#

Optional. This is a list of per-file overrides for each modifier. In the example below, an override is set for acme/weather/v1/weather.proto so that optimize_for is set to CODE_SIZE for only the acme/weather/v1/weather.proto file and not for the rest of the module.

Note that when using the per-file override, the option must be formatted as upper case. The following options can be overridden:

CSHARP_NAMESPACE
GO_PACKAGE (the option name that go_package_prefix modifies)
JAVA_MULTIPLE_FILES
JAVA_OUTER_CLASSNAME
JAVA_PACKAGE (the option name that java_package_prefix modifies)
JAVA_STRING_CHECK_UTF8
OBJC_CLASS_PREFIX
OPTIMIZE_FOR
PHP_METADATA_NAMESPACE
PHP_NAMESPACE
RUBY_PACKAGE

buf.gen.yaml override example

version: v1
managed:
  enabled: true
    override:
      OPTIMIZE_FOR:
        acme/weather/v1/weather.proto: "CODE_SIZE"

buf.gen.yaml v1 config file#

version#

plugins#

plugin#

out#

opt#

path#

revision#

strategy#

protoc_path#

managed#

enabled#

cc_enable_arenas#

csharp_namespace#

except#

override#

go_package_prefix#

default#

except#

override#

java_multiple_files#

java_outer_classname#

java_package_prefix#

default#

except#

override#

java_string_check_utf8#

objc_class_prefix#

default#

except#

override#

optimize_for#

php_metadata_namespace#

php_namespace#

ruby_package#

except#

override#

override#

`version`#

`plugins`#

`plugin`#

`out`#

`opt`#

`path`#

`revision`#

`strategy`#

`protoc_path`#

`managed`#

`enabled`#

`cc_enable_arenas`#

`csharp_namespace`#

`except`#

`override`#

`go_package_prefix`#

`default`#

`except`#

`override`#

`java_multiple_files`#

`java_outer_classname`#

`java_package_prefix`#

`default`#

`except`#

`override`#

`java_string_check_utf8`#

`objc_class_prefix`#

`default`#

`except`#

`override`#

`optimize_for`#

`php_metadata_namespace`#

`php_namespace`#

`ruby_package`#

`except`#

`override`#

`override`#