Reference

Reference / Buf CLI configuration files / v2

buf.yaml

This file has changed between v1 and v2 configurations. See the v1 to v2 migration guide for migration instructions or the v1 reference if you're still using v1 configuration files.

The buf.yaml file defines a workspace, which represents a directory or directories of Protobuf files that you want to treat as a unit. The set consists of one or more packages—see Files and packages for more details about these relationships and how to structure your files.

The buf.yaml config file and field definitions below explain usage for each field. See the lint and breaking change detection overviews for default configurations for those features.

The annotated buf.yaml file below assumes a directory structure like this:

workspace_root
├── buf.yaml
└── proto
    ├── foo
    │   └── foo.proto
    └── bar
        ├── a
        │   └── d.proto
        ├── b
        │   ├── e.proto
        │   └── f.proto
        └── c
            ├── g.proto
            └── h.proto

Annotated buf.yaml configuration

version: v2
# The v2 buf.yaml file specifies a local workspace, which consists of at least one module.
# The buf.yaml file should be placed at the root directory of the workspace, which
# should generally be the root of your source control repository.
modules:
  # Each module entry defines a path, which must be relative to the directory where the
  # buf.yaml is located. You can also specify files or directories to exclude from a module.
  # Directories across modules cannot overlap. For example, "a" and "a/b" cannot be two paths
  # to modules in a given workspace.
  - path: proto/foo
    # Modules can also optionally specify their Buf Schema Repository name if it exists.
    name: buf.build/acme/foo
  # Excluding a subdirectory and a specific .proto file. Note that the paths for exclusion
  # are relative to the buf.yaml file.
  - path: proto/bar
    name: buf.build/acme/bar
    excludes:
      - proto/bar/a
      - proto/bar/b/e.proto
    # A module can have its own lint and breaking configuration, which overrides the default
    # lint and breaking configuration in its entirety for that module. All values from the
    # default configuration are overridden and no rules are merged.
    lint:
      use:
        - DEFAULT
      except:
        - IMPORT_USED
      ignore:
        - proto/bar/c
      ignore_only:
        ENUM_ZERO_VALUE_SUFFIX:
          - proto/bar/a
          - proto/bar/b/f.proto
      # v1 configurations had an allow_comment_ignores option to opt-in to comment ignores.
      #
      # In v2, we allow comment ignores by default, and allow opt-out from comment ignores
      # with the disallow_comment_ignores option.
      disallow_comment_ignores: false
      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 configuration for this module only. Behaves the same as a module-level
    # lint configuration.
    breaking:
      use:
        - FILE
      except:
        - EXTENSION_MESSAGE_NO_DELETE
      ignore_unstable_packages: true
# Dependencies shared by all modules in the workspace. Must be modules hosted in the Buf Schema Registry.
# The resolution of these dependencies is stored in the buf.lock file.
deps:
  - buf.build/acme/paymentapis # The latest accepted commit.
  - buf.build/acme/pkg:47b927cbb41c4fdea1292bafadb8976f # The '47b927cbb41c4fdea1292bafadb8976f' commit.
  - buf.build/googleapis/googleapis:v1beta1.1.0 # The 'v1beta1.1.0' label.
# The default lint configuration for any modules that don't have a specific lint configuration.
#
# If this section isn't present, AND a module does not have a specific lint configuration, the default
# lint configuration is used for the module.
lint:
  use:
    - DEFAULT
# Default breaking configuration. It behaves the same as the default lint configuration.
breaking:
  use:
    - FILE

`version`

Required. Defines the current configuration version. The only accepted values are v2, v1, or v1beta1. To use the configuration as specified below, it must be set to v2. See the buf.yaml specifications for v1 or v1beta1 configurations if you haven't yet migrated to v2.

`modules`

Required. Defines the list of modules that will be built together in this workspace. Any dependencies that the files have on each other are automatically taken into account when building and shouldn't be declared in the deps section.

`path`

Required. The path to a directory containing Protobuf files, which must be defined relative to the workspace root (the directory that contains the buf.yaml file). All path values must point to directories within the workspace.

`name`

Optional. A Buf Schema Registry (BSR) path that uniquely identifies this directory. The name must be a valid module name and it defines the BSR repository that contains the commit and label history and generated artifacts for the Protobuf files in the directory.

`excludes`

Optional. Lists directories within this directory to exclude from Protobuf file discovery. Any directories added to this list are completely skipped and excluded from Buf operations.

We don't recommend using this option, but in some situations it's unavoidable.

`deps`

Optional. Declares one or more modules that your workspace depends on. Each deps entry must be a module name, which is directly associated with a BSR repository, and can also include a specific reference, which is either a commit ID or a label. Dependencies are shared between all modules in the set. Buf tooling already accounts for dependencies between the modules that are part of the set, so they shouldn't be declared here.

Depending on specific module references is an advanced feature—you should depend on the latest commit whenever possible. Your deps don't need to include the :<reference> suffix in most cases.

`lint`

Optional. The lint settings you specify in this section are the default for all modules in the workspace, but can be replaced for individual modules by specifying different settings at the module level. Module-level settings have all of the same fields and behavior as workspace-level settings. If no lint settings are specified for the workspace, it uses the default settings.

`use`

Optional. Lists the categories and/or specific rules to use. For example, this config selects the BASIC lint category and the FILE_LOWER_SNAKE_CASE rule:

buf.yaml – Lint basic usage

version: v2
lint:
  use:
    - BASIC
    - FILE_LOWER_SNAKE_CASE

The DEFAULT category is used if lint is unset.

`except`

Optional. Removes rules or categories from the use list. For example, this config selects all lint rules in the DEFAULT lint category except for ENUM_NO_ALLOW_ALIAS and the rules in the BASIC category:

buf.yaml – Exclude rules or categories from the initial lint setting

version: v2
lint:
  use:
    - DEFAULT
  except:
    - ENUM_NO_ALLOW_ALIAS
    - BASIC

Note that since DEFAULT is the default value for use, this is equivalent to the above:

buf.yaml

version: v2
lint:
  except:
    - ENUM_NO_ALLOW_ALIAS
    - BASIC

`ignore`

Optional. Excludes specific directories or files from all lint rules. If a directory is ignored, then all files and subfolders of the directory are also ignored. The specified paths must be relative to the buf.yaml file. For example, foo/bar.proto is ignored with this config:

buf.yaml – Exclude directories or files from linting

version: v2
lint:
  ignore:
    - foo/bar.proto

`ignore_only`

Optional. Allows directories or files to be excluded from specific lint categories or rules. As with ignore, the paths must be relative to buf.yaml. For example, this config sets up specific ignores for the ENUM_PASCAL_CASE rule and the BASIC category:

buf.yaml – Exclude directories or files from specific categories or rules

version: v2
lint:
  ignore_only:
    ENUM_PASCAL_CASE:
      - foo/foo.proto
      - bar
    BASIC:
      - foo

`disallow_comment_ignores`

In v1 configurations, this key was called allow_comment_ignores and defaulted to false. The default behavior is now to allow comment ignores.

Optional. Default is false if unset. If this option is set to true, you can't add leading comments within Protobuf files to ignore lint errors for certain components within the files:

buf.yaml – Turn off inline comments that ignore rules

version: v2
lint:
  disallow_comment_ignores: true

If the option is unset, for any line in a leading comment that starts with buf:lint:ignore <rule_id>, the linter ignores errors for that rule. For example:

syntax = "proto3";

// buf:lint:ignore PACKAGE_LOWER_SNAKE_CASE
// buf:lint:ignore PACKAGE_VERSION_SUFFIX
package A;

We recommend setting this option to true. In team settings, it's difficult to maintain consistency when individual engineers can easily opt out of lint rules. By using an authors or owners file and keeping all lint ignores in buf.yaml, a small group of reviewers must approve each exception.

As an alternative, you could move the offending types to a separate .proto file, use an authors or owners file to control access to it, and set the corresponding ignore or ignore_only value to point to that file. This allows buf.yaml to have its own access group and stay focused on the organization's defaults.

`enum_zero_value_suffix`

Optional. Controls the behavior of the ENUM_ZERO_VALUE_SUFFIX lint rule. By default, this rule verifies that the zero value of all enums ends in _UNSPECIFIED, as recommended by the Google Protobuf Style Guide. However, organizations can choose a different preferred suffix—for example, _NONE. To set that:

buf.yaml – Change default suffix

version: v2
lint:
  enum_zero_value_suffix: _NONE

That config allows this:

enum Foo {
  FOO_NONE = 0;
}

`rpc_allow_same_request_response`

Optional. Allows the same message type to be used for a single RPC's request and response type. We don't recommend using this option.

`rpc_allow_google_protobuf_empty_requests`

Optional. Allows RPC requests to be google.protobuf.Empty messages. You can set this if you want to allow messages to be void forever and never take any parameters. We don't recommend using this option.

`rpc_allow_google_protobuf_empty_responses`

Optional. Allows RPC responses to be google.protobuf.Empty messages. You can set this if you want to allow messages to never return any parameters. We don't recommend using this option.

`service_suffix`

Optional. Controls the behavior of the SERVICE_SUFFIX lint rule. By default, this rule verifies that all service names are suffixed with Service. However, organizations can choose a different preferred suffix—for example, API. To set that:

buf.yaml – Change suffix to 'API'

version: v2
lint:
  service_suffix: API

That config allows this:

service FooAPI {}

`breaking`

Optional. Specifies the breaking change detection rules enforced on the Protobuf files in the directory.

`use`

Optional. Lists the rules or categories to use for breaking change detection. For example, this config selects the WIRE category and the FILE_NO_DELETE rule:

buf.yaml - Breaking changes detection basic usage

version: v2
breaking:
  use:
    - WIRE
    - FILE_NO_DELETE

The FILE category is used if breaking is unset, which is conservative and appropriate for most teams.

`except`

Optional. Removes rules or categories from the use list. For example, this config results in all breaking rules in the FILE category being used except for FILE_NO_DELETE:

buf.yaml – Exclude rules or categories from the initial breaking change detection setting

version: v2
breaking:
  use:
    - FILE
  except:
    - FILE_NO_DELETE

We don't recommend using this option.

`ignore`

Optional. Excludes specific directories or files from all breaking change detection rules. If a directory is ignored, then all files and subfolders of the directory are also ignored. The specified paths must be relative to the buf.yaml file. For example, foo/bar.proto is ignored with this config:

buf.yaml – Exclude directories or files from breaking change detection

version: v2
breaking:
  ignore:
    - foo/bar.proto

This option can be useful for ignoring packages that are in active development but not deployed in production, especially alpha or beta packages. For example:

buf.yaml – Example of excluding alpha and beta packages

version: v2
breaking:
  use:
    - FILE
  ignore:
    - foo/bar/v1beta1
    - foo/bar/v1beta2
    - foo/baz/v1alpha1

If you want to ignore all alpha, beta, or test packages, we recommend using the ignore_unstable_packages setting instead.

`ignore_only`

Optional. Allows directories or files to be excluded from specific breaking change detection categories or rules. As with ignore, the paths must be relative to buf.yaml. For example, this config sets us specific ignores for the FILE_SAME_TYPE rule and the WIRE category:

buf.yaml

version: v2
breaking:
  ignore_only:
    FILE_SAME_TYPE:
      - foo/foo.proto
      - bar
    WIRE:
      - foo

We don't recommend this option.

`ignore_unstable_packages`

Optional. Ignores packages with a last component that's one of the unstable forms recognized by the Buf linter's PACKAGE_VERSION_SUFFIX rule:

v\d+test.*
v\d+(alpha|beta)\d+
v\d+p\d+(alpha|beta)\d+

For example, if this option is set, these packages are ignored:

foo.bar.v1alpha1
foo.bar.v1beta1
foo.bar.v1test