proposal: cmd/go: GOTOOLCHAIN=mod to use exact version of toolchain directive

[moznion]

Proposal Details

Currently, the local Go runtime determines the actual Go version to use by checking the toolchain directive in the go.mod file when GOTOOLCHAIN=auto is set. If the local Go runtime is newer than the version specified in the toolchain directive, it defaults to the local Go version. This behavior aligns with the Go Toolchain documentation.

However, in some cases—such as in production environments—it may be necessary to enforce a specific Go runtime version, even though Go maintains strong forward and backward compatibility. For example, if the toolchain directive specifies 1.22.8 but the Go runtime in the container is 1.23.2, the actual version used would be 1.23.2. This could lead to unexpected issues if the container runtime is updated (even toolchain is never changed), which should sometimes be blocked to prevent unexpected factors.

While setting GOTOOLCHAIN=<version> is a valid solution but usually this GOTOOLCHAIN environment variables might be in disorder in a project; this is against the DRY principle. I believe it would be more convenient to have an option that always respects the version specified in the toolchain directive as the actual runtime version. This would allow developers to control the Go version for an application simply by modifying the version in the toolchain directive.

As a potential solution, how about introducing an option like GOTOOLCHAIN=mod to achieve this behavior?

[gabyhelp]

Related Issues and Documentation

• extending Go forward compatibility
• extended forwards compatibility for Go #57001 (closed)
• cmd/go: toolchain directive in go.mod being updated unnecessarily #65847
• Forward Compatibility and Toolchain Management in Go 1.21 > Toolchain Management
• Go Toolchains > Go toolchain selection
• Go Toolchains > Introduction
• cmd/go: implement GOTOOLCHAIN=auto
• cmd/go: GOTOOLCHAIN=version+auto doesn't use the named version in go install package@version #69051
• Go Modules Reference > go.mod files > toolchain directive
• go run not adhering to toolchain of go.mod when specifying package version #69817 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[seankhliao]

If you can enforce GOTOOLCHAIN=mod, then you can also enforce GOTOOLCHAIN=target-version.

That said, from experience, if you need to enforce versions, it's better to do that at the time of providing the toolchain into the build environment, including in providing the container. This avoids any possibility of environment misconfiguration and inefficiencies resulting from needing to download and perform a toolchain switch.

[zigo101]

GOTOOLCHAIN=target-version is for all Go projects built on the machine. OP needs a project specific way.

[rsc]

In general we don't want to make it too easy for people to downgrade their go versions.
GOTOOLCHAIN=mod is a forced downgrade eventually, and that's bad.
Avoiding downgrades is the same reason we have minimal version selection.
You can think of GOTOOLCHAIN as being minimal version selection for Go toolchains.

GOTOOLCHAIN=go1.23.4 is like 'go get go@1.23.4' and selects an exact version.
But any non-explicit setting should be some kind of max (minimum value satisfying the input requirements)
that includes the fact that you installed 1.23.6 as a signal that you want to use 1.23.6 or newer.