Many Go projects keep the main package in a `cmd` directory.
Following example could be used to only build the example-cli and example-server binaries:

```nix
{
  subPackages = [
    "cmd/example-cli"
    "cmd/example-server"
  ];
}
```

### `excludedPackages` {#var-go-excludedPackages}

Specified as a string or list of strings. Causes the builder to skip building child packages that match any of the provided values.

### `enableParallelBuilding` {#var-go-enableParallelBuilding}

Whether builds and tests should run in parallel.

Defaults to `true`.

### `allowGoReference` {#var-go-allowGoReference}

Whether the build result should be allowed to contain references to the Go tool chain. This might be needed for programs that are coupled with the compiler, but shouldn't be set without a good reason.

Defaults to `false`

### `goSum` {#var-go-goSum}

Specifies the contents of the `go.sum` file and triggers rebuilds when it changes. This helps combat inconsistent dependency errors on `go.sum` changes.

Defaults to `null`

### `buildTestBinaries` {#var-go-buildTestBinaries}

This option allows to compile test binaries instead of the usual binaries produced by a package.
Go can [compile test into binaries](https://pkg.go.dev/cmd/go#hdr-Test_packages) using the `go test -c` command.
These binaries can then be executed at a later point (outside the Nix sandbox) to run the tests.
This is mostly useful for downstream consumers to run integration or end-to-end tests that won't work in the Nix sandbox, for example because they require network access.

## Versioned toolchains and builders {#ssec-go-toolchain-versions}

Beside `buildGoModule`, there are also versioned builders available that pin a specific Go version, like `buildGo124Module` for Go 1.24.
Similar, versioned toolchains are available, like `go_1_24` for Go 1.24.
Both builder and toolchain of a certain version will be removed as soon as the Go version reaches its end of life.

As toolchain updates in nixpkgs cause mass rebuilds and must go through the staging cycle, it can take a while until a new Go minor version is available to consumers of nixpkgs.
If you want quicker access to the latest minor, use `go_latest` toolchain and `buildGoLatestModule` builder.
To learn more about the Go maintenance and upgrade procedure in nixpkgs, check out the [Go toolchain/builder upgrade policy](https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/go/README.md#go-toolchainbuilder-upgrade-policy).

::: {.warning}
The use of `go_latest` and `buildGoLatestModule` is restricted within nixpkgs.
The [Go toolchain/builder upgrade policy](https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/go/README.md#go-toolchainbuilder-upgrade-policy) must be followed.
:::

## Overriding `goModules` {#buildGoModule-goModules-override}

Overriding `<pkg>.goModules` by calling `goModules.overrideAttrs` is unsupported. Still, it is possible to override the `vendorHash` (`goModules`'s `outputHash`) and the `pre`/`post` hooks for both the build and patch phases of the primary and `goModules` derivation.

Alternatively, the primary derivation provides an overridable `passthru.overrideModAttrs` function to store the attribute overlay implicitly taken by `goModules.overrideAttrs`. Here's an example usage of `overrideModAttrs`:

```nix
{
  pet-overridden = pet.overrideAttrs (
    finalAttrs: previousAttrs: {
      passthru = previousAttrs.passthru // {
        # If the original package has an `overrideModAttrs` attribute set, you'd
        # want to extend it, and not replace it. Hence we use
        # `lib.composeExtensions`. If you are sure the `overrideModAttrs` of the
        # original package trivially does nothing, you can safely replace it
        # with your own by not using `lib.composeExtensions`.
        overrideModAttrs = lib.composeExtensions previousAttrs.passthru.overrideModAttrs (
          finalModAttrs: previousModAttrs: {
            # goModules-specific overriding goes here