What do the GOTOOLCHAIN values auto, local, path and go1.27.0 each tell the go command to do?

## One variable, four shapes of answer `GOTOOLCHAIN` decides which Go toolchain actually executes a `go` command. It accepts four kinds of value, and the differences matter operationally because they trade silence for failure in different places. ### auto The default in official Go distributions. The go command uses the toolchain it is part of, unless the main module's `go` line, its `toolchain` line, or a workspace's `go.work` requires a newer release; then it obtains that release and re-executes as it. This is the setting that makes `git clone && go build` work on a machine whose installed Go is behind the repository. ### local Switching is off. The installed toolchain runs, always. If the module requires a newer Go, the command does not run at all: it errors with a message that names the required version, the version that is running, and the fact that `GOTOOLCHAIN=local` is in force. Nothing is downloaded and nothing is re-executed. Note the corollary: with `local`, a `toolchain` line in go.mod is inert — it is a preference about which release to switch to, and you have forbidden switching. The `go` line's requirement is still checked, because that is a hard minimum. ### path A middle position. Like `auto`, the go command is willing to move to a different version; unlike `auto`, it will not download one. Instead it looks along `PATH` for an executable named for the version it wants, in the `go1.x` form, and runs that. This suits a fleet where a configuration-management system installs approved toolchains and no build is allowed to pull an executable from the network. ### An explicit version name Setting `GOTOOLCHAIN=go1.27.0` pins that toolchain for every command in that environment. Whatever `go` binary you type, the named release runs — it is downloaded on first use if it is not present. This is the strongest form of pinning available and the usual choice for a build image where every job must use one known compiler. Because it is absolute, it does not chase a module that asks for something newer: such a build fails rather than upgrading. ### The +auto and +path floor forms `go1.27.0+auto` and `go1.27.0+path` say "never use anything older than this, and if something requires newer, get it (by download, or from PATH respectively)". These express a *minimum* org-wide toolchain while still letting an individual repository move ahead — useful when you want a security floor rather than an exact pin. ## Where the value comes from Precedence runs: the process environment first, then the go environment file written by `go env -w`, then the default compiled into the distribution. Official releases compile in `auto`; a repackaged Go may choose otherwise, which is a common reason two machines with nominally the same Go disagree. `go env GOTOOLCHAIN` prints the effective value after all of that resolution, which is why it, and not `echo $GOTOOLCHAIN`, is the right thing to collect from a machine. To change it persistently for a user or an image: `go env -w GOTOOLCHAIN=local` (or a version name). To change it for one command, set it in that command's environment. `go env -u GOTOOLCHAIN` removes the written value and restores the built-in default. ## Choosing between them The question behind the setting is: when a repository wants a compiler this machine does not have, what should happen? `auto` says "get it" — convenient, but the build silently depends on a network service and on an executable nobody vetted. `local` says "stop" — loud, reproducible, and it turns every version bump into a human action. `path` says "use one we installed" — the same loudness with a smoother upgrade path. A pinned version name says "this compiler and no other", which is what a release build usually wants. Most organisations end up mixing them: developer laptops on `auto`, build images pinned to a name, and the most sensitive environments on `local` or `path`.