Skip to content

Export a module’s .proto files#

Most Buf workflows reference modules by name and never need the source files locally. Exporting is the escape hatch when an external tool needs the raw .proto files on disk: another Protobuf compiler, a documentation generator, an IDE plugin without BSR awareness, or a CI step that doesn’t have the Buf CLI installed.

For the module’s compiled schema (a FileDescriptorSet) instead of source files, see Download a module’s FileDescriptorSet.

When to use which method#

The BSR offers two ways to pull a module’s .proto files locally:

  • buf export: the default when the Buf CLI is available. It writes individual .proto files into a directory tree, follows imports, and accepts the same module references the rest of the CLI does.
  • curl archive download: when you need plain HTTP or a single zip/tar.gz artifact (CI without a Buf install, ad-hoc scripting, an archive to hand off).

Export with buf export#

The most common pattern: export a BSR module to a local directory.

$ buf export buf.build/grpc/grpc -o /path/to/directory

By default this writes the latest commit on the module’s default label, follows imports, and lays files out at their import-path-relative paths under /path/to/directory. For example, acme/petapis/v1/pet.proto lands at /path/to/directory/acme/petapis/v1/pet.proto.

To pin a specific commit or label, append it after a colon:

$ buf export buf.build/grpc/grpc:334e348dc5854e4b99a3a0d25d8ff376 -o /path/to/directory

Authentication#

buf export uses the standard Buf CLI authentication. For private modules, sign in with buf registry login or set BUF_TOKEN; see Authentication.

Filter what gets exported#

--path keeps only the listed paths (comma-separated for multiple). --exclude-path removes them.

Exclude one directory
$ buf export buf.build/googleapis/googleapis -o /path/to/directory --exclude-path google/geo
Keep only two directories
$ buf export buf.build/googleapis/googleapis -o /path/to/directory --path google/geo,google/longrunning

Drop dependencies#

buf export includes every imported file by default so the output is self-contained. Pass --exclude-imports to keep only the target module’s own files.

Include documentation and license files#

--all writes any documentation (buf.md, README.md) and license files alongside the .proto output. For inputs with multiple modules, those non-.proto files are suffixed with the module name to avoid collisions. --all doesn’t affect dependency inclusion.

$ buf export buf.build/grpc/grpc --all -o /path/to/directory

Other input types#

buf export also accepts Git repositories, tarballs, and local directories: the same input types as the rest of the Buf CLI. For BSR-specific exporting, the patterns above cover the common cases.

Export with curl#

The BSR exposes a zip or tar.gz archive of any module over HTTP, suitable for environments without the Buf CLI:

Syntax
$ curl -fsSL -O https://<host>/<organization>/<module>/archive/<reference>.<format>

Concrete examples:

$ # The latest commit on the default label, as a tarball.
$ curl -fsSL -O https://buf.build/acme/petapis/archive/main.tar.gz

$ # A specific commit, as a zip.
$ curl -fsSL -O https://buf.build/acme/petapis/archive/7abdb7802c8f4737a1a23a35ca8266ef.zip

The URL pieces:

  • <host>: your BSR hostname (buf.build for the public BSR, or your private BSR domain such as your-bsr-instance.example.com).
  • <organization>: the BSR organization that owns the module.
  • <module>: the module name.
  • <reference>: a label name (resolves to the latest commit on that label) or a full commit ID.
  • <format>: tar.gz or zip.

Authentication#

For private modules, pass a BSR token in the Authorization header:

$ curl -fsSL -O \
    -H "Authorization: Bearer ${BUF_TOKEN}" \
    https://buf.build/acme/private-apis/archive/main.tar.gz

Public modules don’t require authentication.

Include dependencies#

The archive contains only the target module’s content by default. Add imports=true to include transitive dependencies and the Well-Known Types:

Archive that includes dependencies
$ curl -fsSL -O "https://buf.build/acme/petapis/archive/main.zip?imports=true"

What’s inside the archive#

The archive contains the module’s .proto files at their import-path-relative paths, the module’s buf.lock, and any documentation or license files the module ships. With imports=true, every transitive dependency’s .proto files appear at their own paths alongside the target module’s files.

Further reading#