Environment Variable: GOTOOLCHAIN

This variable GOTOOLCHAIN controls which Go toolchain is used ¹.

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. The go command can use its bundled Go toolchain as well as other versions that it finds in the local PATH or downloads as needed. By default, Go uses GOTOOLCHAIN=auto. It looks at the go and toolchain lines in your go.mod ² and downloads the required version automatically.

The GOTOOLCHAIN environment setting can force a specific Go version, overriding the go and toolchain lines. If You need to test Your code using a specific (even older) version, adjust the environment variable to that version. Please note that the approach below will only affect the go test command that follows ³:

$ GOTOOLCHAIN=go1.21.0 go test

To permanently change the toolchain to different version use:

$ go env -w GOTOOLCHAIN=go1.25.0
$ go version
go version go1.25.0 linux/amd64

When using GOTOOLCHAIN=auto or GOTOOLCHAIN=<name>+auto, the Go command downloads newer toolchains as needed. Toolchains are downloaded like any other module, meaning that toolchain downloads can be proxied by setting GOPROXY and have their checksums checked by the Go checksum database ⁴.

When using GOTOOLCHAIN=local the Go will only use the version installed on your system.

Conclusion

The Go toolchain version can be adjusted depending on our needs. You can change this variable to point to a specific version of the go toolchain, and then it will be used for all command line tools from now on. This is especially useful if something is relying on a specific version of go or that version is not yet available through the official OS package manager.

Having control over the go toolchain during development is important because:

• Every developer on the team uses the exact same compiler version defined in go.mod.
• Toolchains are downloaded like modules, meaning they are proxied by GOPROXY and verified by the checksum database.
• Your OS stays clean. Go manages Go.