Export modules from the BSR
Within the Buf ecosystem, moving .proto
files around is unnecessary. You can manage dependencies in your modules and
vendor commonly used modules like googleapis/googleapis
from the Buf Schema Registry (BSR) community modules. However,
tools other than the Buf CLI may require all .proto
files to be present locally.
To export .proto
files from the BSR, you can either:
- use the Buf CLI's
buf export
command - download and extract an archive file
Export with the Buf CLI
The buf export
command allows you to copy .proto
files to your local environment from many types of sources,
including the BSR, a Git repository, or a .tar
file. From there you can inspect them or move them into other tools or
legacy systems.
The basic buf export
command requires a local destination directory path for the output and defaults to the current
local directory as the source:
$ buf export -o /path/to/directory
You can also specify a BSR module or a Git repository as the source:
$ buf export buf.build/grpc/grpc -o /path/to/directory
$ buf export buf.build/grpc/grpc:334e348dc5854e4b99a3a0d25d8ff376 -o /path/to/directory
$ buf export https://github.com/bufbuild/protovalidate.git -o /path/to/directory
When exporting from the BSR, you can append a specific commit or label reference to the module name, preceded by
a colon (:
). By default, exporting from the BSR includes all dependencies.
You can also limit the output to a subset of the source by either excluding or including specific paths to a directory or file (multiple paths must be separated by commas):
$ buf export buf.build/googleapis/googleapis -o /path/to/directory --exclude-path google/geo
$ buf export buf.build/googleapis/googleapis -o /path/to/directory --path google/geo,google/longrunning
Export with curl
You can also request an archive of a module from the BSR using the curl
command. It downloads a zip or tarball archive
to your local environment. The download command requires a BSR module as the source, and has this syntax (the example
shows a request for the latest commit on the default label):
$ curl -sOJ "https://buf.build/acme/petapis/archive/main.tar.gz"
$ curl -sOJ "https://buf.build/acme/petapis/archive/7abdb7802c8f4737a1a23a35ca8266ef.zip"
$ curl -sOJ "https://buf.build/acme/petapis/archive/v1.0.2.zip"
Including dependencies
By default, the module archive includes only the specified module's content, excluding any dependencies. You can
include all of the target module's dependencies, including the
Well Known Types, by adding the imports=true
query parameter:
$ curl -sOJ "https://buf.build/acme/petapis/archive/main.zip?imports=true"
Related docs
- Browse the
buf export
command reference for details about all source types and flags.