Skip to main content

Build an Image

More information

To verify that Buf can build your repository:

$ buf build

If you've followed this tour this command should have exit code 0 and no output.

This uses the internal compiler and builds an Image, which is a FileDescriptorSet with Buf-specific metadata.

The buf build command can be used:

  • For verifying that your Protobuf files compile, as we did above.
  • For storing the current state of your Protobuf files, for use with the breaking change detector. With the currently released feature set, this will be the primary use case of this command.
  • As input to protoc or protoc plugins.

An output location is required, but Buf stops short if you specify /dev/null as the output location, and will stop short if nul is specified on Windows when we have Windows Support.

Images can be outputted in one of two formats:

  • Binary
  • JSON

Either format can be compressed using Gzip or Zstandard.

Buf parses the file extension to determine the output format, however the option format can be given to override this default behavior. The value - is special-cased to mean stdout. See the Input documentation for more details (however we recommend deferring this until the end of the tour).

$ buf build -o image.bin
$ buf build -o image.bin.gz
$ buf build -o image.bin.zst
$ buf build -o image.json
$ buf build -o image.json.gz
$ buf build -o image.json.zst
# Output to stdout in binary format
$ buf build -o -
# Output to stdout in JSON format
$ buf build -o -#format=json
# Output in gzipped binary format even though there is a bin extension
# Not recommended
$ buf build -o image.bin#format=bin,compression=gzip

When combined with jq, buf build allows for introspection. For example, to see a list of all packages:

$ buf build --exclude-source-info -o -#format=json | jq '.file[] | .package' | sort | uniq | head

To strip the Buf-specific metadata and only output a FileDescriptorSet:

$ buf build --as-file-descriptor-set -o -#format=json

However, we recommend outputting full Images as it helps Buf do it's job in other areas, and Images are wire-compatible with FileDescriptorSets - protoc will happily process Images and ignore the extra metadata.