Dependency Management

A module can declare dependencies on other modules, which is configured in the deps key of your buf.yaml. You can add dependencies by adding their module name to the deps list. For example:

version: v1
name: buf.build/acme/weather
deps:
  - buf.build/acme/units

Although we do not recommend it, in some situations you may need to pin a module to a specific version. You can do this by specifying a tag, a commit name, or a draft name in your deps after the : delimiter. Ideally, authors keeps modules backwards-compatible and avoid breaking changes, so you can always rely on the latest version.

deps:
  - buf.build/acme/units:1c473ad9220a49bca9320f4cc690eba5

Once a dependency is added to the configuration file, you need to run:

$ buf mod update

This updates all your deps to their latest version and is captured in a buf.lock file.

You can now import the Protobuf types just like you would if you had the files locally:

package acme.weather.v1;

import "acme/units/v1/unit.proto";

message Forecast {
  string description = 1;
  acme.units.Degree temperature = 2;
}

The buf CLI automatically resolves the module(s) specified in the deps list.

See the Usage section for a detailed example.

To execute buf commands below make sure you are authenticated. Obtain a token from the BSR and run:

$ buf registry login

Follow the prompts to enter your username and password (API Token). This adds an entry into your $HOME/.netrc (Linux or macOS) or %HOME%/_netrc (Windows).

Push a module

To push to the BSR, your module must build successfully. This means that you are able to run buf build successfully on your module and your module has no dependencies pinned to a draft commit.

Before you can push a module into the BSR, a repository must exist and you must own or have access to that repository. A repository can be created either through the UI or from the command line with buf.

If you want to collaborate with other users on a module, select an organization as the owner of the repository.

1. Create a Repository

Through the UI log in at https://buf.build/login and navigate to Your repositories and click Create Repository. Select an owner for the repository and give it a repository name. The visibility can be either public or private.

Alternatively, use the CLI run this command:

$ buf beta registry repository create <MODULE_NAME> --visibility [public,private]

The module name takes the form <remote>/<owner>/<repository_name> (for example, buf.build/acme/weather). The --visibility flag is required and must be one of: private or public.

2. Configure a name

You'll need to configure your buf.yaml file to match the BSR repository. To do so, add the module name as a name key:

version: v1
name: buf.build/acme/weather

3. Push to the Repository

Push your module to the BSR by running this command:

$ buf push

This command returns the commit reference.

One of the main benefits of a centralized, Protobuf-aware registry is you're guaranteed not to push broken modules. This means that consumers can have confidence that modules hosted on the BSR always compile.

Suppose we mistyped an identifier:

syntax = "proto3";

package units.v1;

messag Metric {
    int64 other = 1;
}

If we try to buf push to the BSR we'll get an immediate error:

Failure: units/v1/metric.proto:5:1:syntax error: unexpected identifier.

Sure you can have CI workflows to automatically catch compilation errors, but by using the BSR these guarantees are made available to everyone out-of-the-box.

That's it. This module can now be consumed as a first class dependency and its generated documentation can be viewed on the BSR.

Add a dependency

A module can declare dependencies on other modules, which is configured in the deps key of your buf.yaml. You can add dependencies by adding their module name to the deps list. For example:

version: v1
name: buf.build/acme/weather
deps:
  - buf.build/acme/units

Although we do not recommend it, in some situations you may need to pin a module to a specific version. You can do this by specifying a tag, a commit name, or a draft name in your deps after the : delimiter. Ideally, authors would keep modules backwards-compatible and avoid breaking changes, so you can always rely on the latest version.

deps:
  - buf.build/acme/units:1c473ad9220a49bca9320f4cc690eba5

Once a dependency is added to the configuration file, you need to run:

$ buf mod update

This updates all your deps to their latest version and is captured in a buf.lock file.

You can now import the Protobuf types just like you would if you had the files locally:

package acme.weather.v1;

import "acme/units/v1/unit.proto";

message Forecast {
  string description = 1;
  acme.units.Degree temperature = 2;
}

The buf CLI automatically resolves the module(s) specified in the deps list.

Example

If, for example, you are using one of the files from the googleapis repository in your Protobuf files, and you're having to copy files into your local Protobuf generation tree, you can instead use buf to manage this dependency for you.

To include dependencies in your build add the deps key to your buf.yaml file and list the modules your build depends on. Example:

version: v1
deps:
  - buf.build/googleapis/googleapis
lint:
  use:
    - DEFAULT
breaking:
  use:
    - FILE

After adding dependencies in buf.yaml run this command:

$ buf mod update

This updates all your deps to their latest version and gets captured in a buf.lock file. You do not need to make any changes to this file and if using a version control system, commit it along with your Protobuf files.

# Generated by buf. DO NOT EDIT.
version: v1
deps:
  - remote: buf.build
    owner: googleapis
    repository: googleapis
    commit: 62f35d8aed1149c291d606d958a7ce32

Once your dependencies are updated, you can run buf build and the buf CLI resolves hosted module dependencies by leveraging the BSR.

For a more in-depth example see the Tour