DocsCommunityTestimonialsUsersGitHubTwitterBlogJobs
HomeDocs
DocsCommunityTestimonialsUsersGitHubTwitterBlogJobsTermsPrivacyCookies
TermsPrivacyCookies
Hey! These docs are for version 2.8, which is no longer officially supported. Click here for the latest version, 2.15!

Go support is alpha stage

We are done implementing the initial core functionality for Pants's initial Go support ([tracked here](🔗)). However, there may be some edge cases we aren't yet handling. There are also some features that are not yet supported like Cgo files and vendoring, which we'd love your input on how to prioritize!

Please share feedback for what you need to use Pants with your Go project by either [opening a GitHub issue](🔗) or [joining our Slack](🔗)!

Why use Pants with Go?

Go's builtin tooling is already excellent! Many projects may be fine only using Go's tooling, although Pants offers some unique benefits:

  • A consistent interface for all languages/tools in your repository, such as being able to run `./pants fmt lint check test package`.

  • Integration with Git, such as running `./pants --changed-since=HEAD test`.

  • Caching, such as caching test results on a per-package basis.

  • [Remote execution and remote caching](🔗).

  • [Advanced project introspection](🔗), such as finding all code that transitively depends on a certain package.

Example Go repository

Check out [github.com/pantsbuild/example-golang](🔗) to try out Pants's Go support.

Assumes you're using a single Go module

We do not yet support multiple first-party Go modules. If you are using multiple modules, please feel free to share your use case on https://github.com/pantsbuild/pants/issues/13114. (For example, if you are using a `replace` directive.)

## Initial setup

First, activate the Go backend and set the expected Go version in `pants.toml`:


You can also set `[golang].go_search_paths` to influence where Pants looks for Go, e.g. `["/usr/bin"]`. It defaults to your `PATH`.
Then run [`./pants tailor`](🔗) to generate BUILD files. This will add a `go_mod` target where you have your `go.mod` file, along with a `go_binary` target in every directory where you have `package main`.

The `go_mod` target generates a `go_first_party_package` target for each directory in your project with `.go` files, and a `go_third_party_package` target for each package belonging to the modules declared in your `go.mod`. These package targets are the building blocks for Pants, although you rarely will need to interact with them directly.
You can run `./pants list ::` to see all targets in your project, including generated `go_first_party_package` and `go_third_party_package` targets:

`go.mod` and `go.sum` need to be up-to-date
Pants does not yet update your `go.mod` and `go.sum` for you; it only reads these files when downloading modules. 
You will need to run `go mod download all` and/or `go mod tidy` to update these files when you add a new third-party module or change its version.
## Package and run binaries
To run a binary, use `./pants run path/to/main_pkg:` (note the colon). You can pass through arguments with `--`, like this:

You can also package your binaries (aka `go build`) by using `./pants package`. `package ::` will build all your project's binaries, whereas `package path/to/main_pkg:` will build only the binary in that directory.

By default, Pants names the binary with the scheme `path.to.directory/target_name`, e.g. `cmd.deploy/bin`. You can set the field `output_path` to use a different name:

`embed` support coming in Pants 2.9
We're making progress on adding support for `resources` / the `embed` directive. See https://github.com/pantsbuild/pants/issues/13193.
## Compile code
To manually check that a package compiles, use `./pants check`:

(Instead, you can simply run `package`, `run`, and `test`. Pants will compile all the relevant packages.)
## Run tests
To run tests, use `./pants test`:

You can pass through arguments with `--`, e.g. `./pants test pkg/deploy: -- -v -run TestFoo`.
`testdata` folder not yet supported
Please comment on https://github.com/pantsbuild/pants/issues/13200 if you need this feature for your project so that we can bump its priority.
## Gofmt
Gofmt is activated by default when you activate the Go backend. Simply run `./pants fmt` and `./pants lint`:

If you'd like to disable Gofmt, you can set this:

Support for [`[gofmt].args` is upcoming](🔗), which will allow you to use [Gofmt's `-r` feature](🔗).
Support for `go vet` is also upcoming.