In go.mod, the go line is the minimum Go version a module needs. The toolchain line suggests a toolchain to use. The GOTOOLCHAIN setting controls whether the go command may switch to or download a newer toolchain. The default behavior allows switching to one required by go.mod.
Definitions
go line. The minimum Go version needed to use the module. Since Go 1.21 it is mandatory. A toolchain refuses to load a module that requires a newer version, and the line also sets the language version the compiler enforces.
toolchain line. A suggested toolchain. If omitted, it is implicitly the same as the go line.
GOTOOLCHAIN. An environment setting that decides which toolchain the go command runs.
GOTOOLCHAIN values
| Value | Behavior |
|---|---|
local | Always use the bundled toolchain |
auto | Same as local+auto, the standard default |
path | Same as local+path |
go1.21.3 | Always use that exact toolchain |
name+auto | Start with the named toolchain, switch if go.mod needs newer |
name+path | Like +auto but search PATH only, with no download |
Why this is a security matter
Automatic switching is convenient, because a dependency can say it needs a newer Go and your tooling follows. It also means your build can download and run a toolchain you did not install. Go documents the safeguards: toolchains are modules served under golang.org/toolchain, verified through the checksum database, and downloads honor GOPROXY. If GOSUMDB is off, toolchain downloads fail because they cannot be verified.
For locked down build environments, the options are clear:
- Set
GOTOOLCHAIN=localif you want builds to use only what is installed and fail on a mismatch. - Use
+pathif you want to allow switching but only to toolchains you placed on PATH. - Pin an exact version such as
go1.26.9when you want reproducible builds.
How a version gets chosen
When a command needs a newer version, Go picks the oldest candidate that satisfies the requirement from the latest release candidate of an unreleased version, the latest patch of the most recent release, or the latest patch of the previous release. It then writes the new go and toolchain lines, so later runs select it without a message.
Handy commands
go env GOTOOLCHAIN
go get go@1.26.9
go get toolchain@none
Practical advice
- Set the
goline to the lowest version your code truly needs, and keep it on a supported release. - Decide per environment: developers may use
auto, release builds may uselocal. - Log the toolchain version in CI so a silent switch is visible.
- Review any pull request that raises the go line, because it changes the build requirement for everyone.
See How long is a Go version supported for the support rule.
Try it yourself
The gate pull request demo shows a check running on a change. A go line bump is a good thing to gate.
Click through it at your own pace, or open it full screen.
Safeguard policies and gates can run checks on pull requests. The free scan is at gold.safeguard.sh/scan.
Quick check
Does Go download toolchains by default?
If a newer toolchain is required by go.mod and the setting allows it, yes. Set GOTOOLCHAIN to local to prevent that.
Is a downloaded toolchain verified?
Per the Go documentation, it is verified through the checksum database.
Sources
Last reviewed: 19 October 2026.
