Build an Image

To verify that Buf can build your repository:

$ buf image build -o /dev/null

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

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

$ buf image 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 image 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.