Toolchains in Go¶

This is a blog for Go toolchains, I will try to explain what is toolchain, how to use it and why Go needs it.

Why Go Toolchain¶

Go hides a lot of internal complexities greatly with a unified entry go binary, and you can run several go commands to meet requirements.

However, go has provided a lot of additional tools as a bundle, along with the standard libraries. For example, go tool shows all available local tools.

$ go tool
addr2line
asm
buildid
cgo
compile
# etc ...

Some of the functionalities are provided by underlying tools, rather the binary go itself. For example, the compiler tool under cmd/compile inside std.

Compile, compiles a single Go package comprising the files named on the command line. It then writes a single object file named for the basename of the first source file with a .o suffix.

It means the go binary has a lot of related tools, as all of them are put under the same repository and released together. Starting in Go 1.21, the Go distribution consists of a go command and a bundled Go toolchain, which is the standard library as well as the compiler, assembler, and other tools.

As a result, when go is used to run a tool, how could a project controls the toolchain version they required? Here are 2 examples:

• Minimal go tool is required: the go tool must not be lower than a certain version.
• Specify go tool version: a certain version tools are desired.

The go binary is the entry, so how go tries to avoid this behavior? Go toolchains is introduced to ensure the go binary helps choose a correct go toolchain version.

What is Go Toolchains¶

The choice of Go toolchain being used depends on the GOTOOLCHAIN environment setting,
and the go and toolchain lines in the main module’s go.mod file,
or the current workspace’s go.work file.

In the standard configuration, the go command uses its own bundled toolchain when that toolchain is at least as new as the go or toolchain lines in the main module or workspace.

Hence, the final go version selected to use usually is the highest when you run go version(go>=go1.21.0) under a main module. The usually only fits when the setting is auto.

module mod.com
go 1.22
toolchain go1.23.0

module mod.com
go 1.22
toolchain go1.23.0

module mod.com
go 1.24
toolchain go1.23.0

Note that the go toolchain takes effects on main module only, go won't respect the toolchain setting from another module. It's a direct and not transitive setting.

GOTOOLCHAIN ENV¶

The GOTOOLCHAIN environment setting can force a specific Go version, overriding the go and toolchain lines. Hence, you can use your global go to trigger any go version(>=go1.21.0) you like.

This mechanism has an internal version switch from the global version to specified version. For example, specify GOTOOLCHAIN=go1.22.10 allows you use go1.22.10 instead go1.24.0 installed globally.

$ go version
go version go1.24.0 darwin/arm64

$ GOTOOLCHAIN=go1.22.10 go version
go version go1.22.10 darwin/arm64

You may find this approach override the go and toolchain lines, so how to use toolchain to satisfy the following requirement?

• given global installed go1.24.0
• want to use go1.22.10 to trigger go command
• want to respect local toolchain, and select go1.23.6 as final go version.

This could be resolved by adding +auto after go version:

- GOTOOLCHAIN=go1.22.10 go version
+ GOTOOLCHAIN=go1.22.10+auto go version

GOTOOLCHAIN Setting¶

Besides the 2 examples shown above, Go toolchain offers more flexibilities. The go command selects Go toolchain to use based on GOTOOLCHAIN setting with the following rules. It also provides several ways to specify it.

# This file contains the initial defaults for go command configuration.
# Values set by 'go env -w' and written to the user's go/env file override.
# The environment overrides everything else.

# Use the Go module mirror and checksum database by default.
# See https://proxy.golang.org for details.
GOPROXY=https://proxy.golang.org,direct
GOSUMDB=sum.golang.org

# Automatically download newer toolchains as directed by go.mod files.
# See https://go.dev/doc/toolchain for details.
GOTOOLCHAIN=auto

GOTOOLCHAIN Selection¶

The topic above shows how to set up the GOTOOLCHAIN, but in What is Go Toolchains we mentioned the toolchain is selected based on env var and toolchain inside go.mod.

Here, what do the Setting and Selection work together?

First of all, the Setting refers to the default toolchain, and the go allows to specify a module/workspace level toolchain configuration, and Module and workspace configuration describes it with details.

The toolchain line declares a suggested toolchain to use with the module or workspace. As described in “Go toolchain selection” below, the go command may run this specific toolchain when operating in that module or workspace if the default toolchain’s version is less than the suggested toolchain’s version.

If the toolchain line is omitted, the module or workspace is considered to have an implicit toolchain goV line, where V is the Go version from the go line.

Then, after knowing the toolchain inside go.mod and setting, we check how the selection works.

Trace go toolchain selection by adding toolchaintrace=1 to the GODEBUG environment variable.

Go Line Limitation¶

Go toolchain refuses to load a module whose go version is higher(e.g. go1.22.1 wants to load go1.22.2).

The go line for each module sets the language version the compiler enforces when compiling packages in that module.

Before Go 1.21, Go toolchains treated the go line as an advisory requirement: if builds succeeded the toolchain assumed everything worked, and if not it printed a note about the potential version mismatch.

Go 1.21 changed the go line to be a mandatory requirement instead. Before Go 1.21, toolchains did not require a module or workspace to have a go line greater than or equal to the go version required by each of its dependency modules.

For example, given the cases:

• main module has go1.20 in go.mod.
• use a module requires go1.22 but no new language feature.

Differences Between 'go' and 'toolchain' in go.mod/go.work¶

The go directive is a limitation, but the go toolchain is a suggestion. Go toolchain applies its suggestion by switching go version silently when the GOTOOLCHAIN setting is auto.