Last updated August 30, 2024

This guide outlines how to manage the Go toolchain and dependencies on Heroku using Go Modules.

The Using Go Modules blog post covers the most common usage of the tool. We cover the most common activities in this article.

Build Configuration

go.mod Directives

When pushing code that uses Go modules, Heroku uses several directives in the go.mod file to configure your build. These directives are:

• go: This directive is usually at the top of the go.mod file. It describes the minimum Go version that can be used to compile the app. This value is used to select the version of Go to install on Heroku at build time. This value doesn’t include a minor version. Heroku resolves the minor version to the latest available. For example: go 1.21

• require: This field defines the module and minimum versions of those modules that must be installed. These modules are downloaded, unless they’re already in the vendor/ directory. For example: require github.com/gin-gonic/gin v1.10.0

go.mod Heroku Build Directives

Additionally, Heroku supports build directives in the go.mod file.

• // +heroku goVersion <version>: You can use this field to specify a different Go version than specified by the go directive. Using this directive you can override the go directive for Go version selection. For example: // +heroku goVersion go1.22.6

• // +heroku install <packagespec>[ <packagespec>]: You can use a space separated list of the packages you want to install here. If not specified, Heroku defaults to detecting and installing the main packages in the code base. If this process isn’t what you want, you can instruct the buildpack to only build certain packages via this option. Other common choices are: ./cmd/... (all packages and sub packages in the cmd directory) and ./... (all packages and sub packages of the current directory). For example: // +heroku install ./cmd/... ./special

Go Module Authentication With go.sum

If a go.sum is provided, the Go toolchain verifies that the installed modules match the expected cryptographic hashes. This file is generated and updated by many go module-aware commands. Heroku recommends committing go.sum to the repository for an extra layer of security.

Go Module Vendoring With vendor/modules.txt

If a vendor/modules.txt is present, the Go toolchain attempts to use modules included in the repository under the /vendor directory rather than downloading them from the internet. You can use this vendoring strategy to reduce build timeouts, errors, or improve build speed. You can generate the required files by running go mod vendor, then committing the result.

Install or Update Go Modules

Go modules are included with the Go toolchain. See the instructions for installing the Go toolchain.

Project Initialization

1. Run go mod init <project> to generate go.mod.
2. Run go mod tidy to install dependent modules and generate a go.sum.
3. Optionally run go mod vendor to vendor dependencies if you want to vendor modules.
4. Inspect the changes with git diff or a similar command.
5. Commit the changes with git add -A; git commit -am "Setup Go modules"

Adding Dependencies

1. Run go get -u <module>. For example: go get -u github.com/gin-gonic/gin.
2. Add import <module> directives in your .go files where needed.
3. Inspect the changes with git diff or a similar command.
4. Commit the changes with git add -A vendor; git commit -am "Add dependency <package>"

Dependency Status

1. Run go mod graph to get a summary of modules.
2. Run go mod verify to check module authenticity.

Updating an Existing Dependency

1. Run go get <module> or go get <module>@<version>.
2. Inspect the changes with git diff or a similar command.
3. Commit the changes with git add -A vendor; git commit -m "Update <module>".

Removing Unused Dependencies

1. Run go mod tidy
2. Inspect the changes with git diff or a similar command.
3. Commit the changes with git add -A vendor; git commit -m "Remove unused dependencies".