Hey! These docs are for version 2.13, which is no longer officially supported. Click here for the latest version, 2.17!

When your Go code imports Protobuf generated files, Pants will detect the imports and run the Protoc compiler to generate then compile those files.

Example repository

See [the codegen example repository](🔗) for an example of using Protobuf to generate Go.

Benefit of Pants: generated files are always up-to-date

With Pants, there's no need to manually regenerate your code or check it into version control. Pants will ensure you are always using up-to-date files in your builds.

Thanks to fine-grained caching, Pants will regenerate the minimum amount of code required when you do make changes.

`go mod tidy` will complain about missing modules

Because Pants does not save generated code to disk, `go mod tidy` will error that it cannot find the generated packages.

One workaround is to run `./pants export-codegen ::` to save the generated files.

## Step 1: Activate the Protobuf Go backend

Add this to your `pants.toml`:

This adds the new [`protobuf_source`](🔗) target, which you can confirm by running `./pants help protobuf_source`.

To reduce boilerplate, you can also use the [`protobuf_sources`](🔗) target, which generates one `protobuf_source` target per file in the `sources` field.

## Step 2: Set up your `go.mod` and `go.sum`

The generated Go code requires `google.golang.org/protobuf` to compile. Add it to your `go.mod` with the version you'd like. Then run `go mod download all` to update your `go.sum`.

## Step 3: Add `option go_package` to `.proto` files

Every Protobuf file that should work with Go must set `option go_package` with the name of its Go package. For example:

Multiple Protobuf files can set the same `go_package` if their code should show up in the same package.

## Step 4: Generate `protobuf_sources` targets

Run [`./pants tailor ::`](🔗) for Pants to create a `protobuf_sources` target wherever you have `.proto` files:

Pants will use [dependency inference](🔗) for any `import` statements in your `.proto` files, which you can confirm by running `./pants dependencies path/to/file.proto`.

If you want gRPC code generated for all files in the folder, set `grpc=True`.

If you only want gRPC generated for some files in the folder, you can use the `overrides` field:

## Step 5: Confirm Go imports are working

Now, you can import the generated Go package in your Go code like normal, using whatever you set with `option go_package` from Step 3.

Pants's dependency inference will detect Go imports of Protobuf packages, which you can confirm by running `./pants dependencies path/to/file.go`. You can also run `./pants check path/to/file.go` to confirm that everything compiles.

Run `./pants export-codegen ::` to inspect the files

`./pants export-codegen ::` will run all relevant code generators and write the files to `dist/codegen` using the same paths used normally by Pants.

You do not need to run this goal for codegen to work when using Pants; `export-codegen` is only for external consumption outside of Pants, e.g. to get `go mod tidy` working.

## Buf: format and lint Protobuf

Pants integrates with the [`Buf`](🔗) formatter and linter for Protobuf files.

To activate, add this to `pants.toml`:

Now you can run `./pants fmt` and `./pants lint`:

Use `./pants fmt lint dir:` to run on all files in the directory, and `./pants fmt lint dir::` to run on all files in the directory and subdirectories.

Temporarily disable Buf with `--buf-fmt-skip` and `--buf-lint-skip`:

Only run Buf with `--lint-only=buf-fmt` or `--lint-only=buf-lint`, and `--fmt-only=buf-fmt`: