Toolchain Versions and Compatibility

Go is released every six months, in February and August. The Go team describes the cycle as about four months of development followed by three months of release freeze, with the development of the next release starting before the previous one ships. The target milestones, each aligned to a week of a month:

Exact dates move with holidays, but the cycle is steady, as the history shows:

Dates are the dates of the .0 releases. The support policy is one sentence: each major Go release is supported until there are two newer major releases. So with 1.27 current, both 1.27 and 1.26 receive fixes for critical problems, including security problems, as minor releases; when Go 1.28 ships, Go 1.26 stops. Three consequences follow for projects: a production service should be on the current or previous release, a library should say which older release it still needs (the go line, below), and a CI matrix of "current and previous" matches what the Go team itself supports.

The diagram lists the headline changes each release brought; each topic has its own page in this section. The toolchain line and the godebug directive on the timeline are the subject of this page.

Source: Go Wiki: Go Release Cycle, Release History and Go 1.27 release notes

The compatibility promise is why a Go program from 2015 usually builds with today’s toolchain. Go 1 defines the language specification and the "standard packages" of the core library, and the promise is that programs written to that specification continue to compile and run correctly, unchanged, over the lifetime of the specification. Compatibility is at the source level: binaries are not guaranteed to link across releases, so you recompile after an upgrade. New releases may add APIs and features, but not in a way that breaks existing Go 1 code. Each set of release notes repeats the promise in its first paragraph, and the Go 1.27 notes expect almost all programs to continue to compile and run as before.

The promise has documented exceptions. They are narrow, but a robust program should know them:

The unkeyed-literal rule is the one most likely to affect ordinary code, and go vet knows it. This program builds a csv.ParseError both ways; both work today, but only one is guaranteed to keep working:

Source: Go 1 and the Future of Go Programs and cmd/vet: composites

Compatibility has a second mechanism for the cases the promise lets through. When a change is allowed by Go 1 but may break some programs (a security fix, say, or HTTP/2 enabled by default), the Go team adds a GODEBUG setting that opts a program back into the old behavior, and, since Go 1.21, makes that setting follow the module’s go line automatically. That mechanism has its own section below. The blog post Backward Compatibility, Go 1.21, and Go 2 explains the thinking: the go line has stopped being advisory and has become a contract between the code and the toolchain.

Source: The Go Blog: Backward Compatibility, Go 1.21, and Go 2

The go.mod file (and go.work for workspaces) states two versions:

If the go line is missing, the module is treated as having go 1.16 (a missing go line in go.work means go 1.18). If the toolchain line is missing, it is implied: go 1.21.0 with no toolchain line is read as toolchain go1.21.0. The version forms go 1.27 and go 1.27.0 differ since Go 1.21: 1.27 denotes a language version that is older than every release of it, so use it when you do not need a specific patch release.

The go line has a second job. It sets the language version the compiler enforces for every package in the module, and the toolchain turns it into -lang=go1.27 on the compile command, as the previous page showed. A newer toolchain compiling an older module therefore still follows the older language rules where they differ. The demonstration has three parts.

Part 1: a language feature that is too new for the go line. Range over an integer arrived in Go 1.22. A module that says go 1.21 cannot use it, even when the toolchain is Go 1.27:

Source: Go Modules Reference: go directive and Go 1.22 release notes: language

Part 2: the same source behaves differently under different go lines. Go 1.22 changed for loops so that each iteration has its own copy of the loop variable. The change is gated on the go line, so existing code keeps its old meaning until you raise the line:

Source: The Go Blog: Fixing For Loops in Go 1.22 and Go 1.22 release notes: language

Raising the go line is therefore a behavior change as well as a permission, which is why a go line bump belongs in a reviewed commit (and why the go fix modernizers described in Formatting, vet, fix and Static Analysis help afterwards).

Part 3: a file can raise its own language version. A //go:build constraint that implies at least go1.21 sets the language version of that one file to the constraint’s version. A module that supports go 1.21 can therefore carry one file with newer syntax and a fallback for older toolchains:

Source: cmd/go: Build constraints

Source: cmd/go: Build constraints

Source: Go Modules Reference: go directive, Go Toolchains: Module and workspace configuration and Go 1.22 release notes: language

The go command that you install is a launcher as well as a toolchain. At startup it decides which toolchain to run, using the GOTOOLCHAIN setting and the lines in the current module or workspace. The setting itself is found like any Go environment setting: a non-empty value in the process environment wins, then the user’s default file (go env -w, see below), then the $GOROOT/go.env file inside the installation, which in a standard toolchain says GOTOOLCHAIN=auto; with no default at all it behaves as local.

The selection rules, after reading go.work (or go.mod when there is no workspace) in the current directory, are exactly these:

Here are the real behaviors, with a module whose go line is deliberately newer than anything installed. First the failing cases, offline:

local refuses to continue; auto tries to download go1.99.0 and, with no network and no such toolchain, fails; path only searches PATH. The same module with a toolchain line that is newer than the default would be switched to that toolchain the same way; a toolchain line older than the running toolchain is ignored, so with GOTOOLCHAIN=local a line such as toolchain go1.99.1 does not stop a build (the go line is what local enforces).

To watch the success path without network, put a stand-in program named go1.27.9 on PATH. This one is a two-line shell script that only prints its arguments, so it also proves the mechanism: the go command runs the toolchain with the matching name and forwards the arguments. The module says go 1.27.9, newer than the bundled go1.27.2:

(The path to fakebin is shortened.) GODEBUG=toolchaintrace=1, available since Go 1.24, prints why a toolchain was chosen and where it was found; it is the first thing to try when the wrong toolchain runs. When the requested toolchain is the running one, the trace says go: using local toolchain go1.27.2.

Source: Go Toolchains: Go toolchain selection and Go 1.24 release notes: Go command

A GODEBUG setting is a key=value pair that controls one part of a Go program’s behavior. The environment variable holds a comma-separated list (GODEBUG=http2client=0,http2server=0 disables HTTP/2 in both the client and the server); unknown settings in the variable are ignored. What makes GODEBUG central to compatibility is that a program also has default values compiled in, and the go line selects them.

The rules for the defaults of a setting not named in the environment, in order of precedence:

So a module that says go 1.20, built with Go 1.27, gets the defaults of Go 1.20 wherever a GODEBUG setting covers a difference. A runnable case is panic(nil): before Go 1.21 it could be recovered as nil; since Go 1.21 it panics with a *runtime.PanicNilError, controlled by the panicnil setting:

Source: runtime: PanicNilError and GODEBUG history: Go 1.21

go list -f '{{.DefaultGODEBUG}}' <main package> prints the defaults compiled into a main package: only the differences from the base toolchain defaults, which is why the go 1.27 module prints nothing. The same list is recorded in the binary and shown by go version -m as a DefaultGODEBUG entry in its build settings. The full list for a go 1.20 module (abridged above to three settings) shows how many separate behaviors the go line governs.

There are four ways to change a setting. First, at run time, for one process, with the environment variable:

Second, for the whole module, with a godebug directive in go.mod, as a single line:

Third, as a block, using the special key default to take every unlisted setting from a Go version, separately from the module’s language version. This one asks for Go 1.21 semantics and then for the old panic(nil) behavior:

Fourth, for one program, with a //go:debug directive at the top of a file of its main package:

Some rules to remember:

Source: Go, Backwards Compatibility, and GODEBUG and Go Modules Reference: godebug directive

GOEXPERIMENT is a build-time variable that turns toolchain and runtime experiments on or off. It is read by go build, not at run time, and it is how the Go team ships a feature to early adopters before it is stable. Experiments are not covered by the compatibility promise; if you use one, label it in your own documentation.

The syntax is a comma-separated list. A name enables an experiment, a no prefix disables one, and none clears all experiment flags. An unknown name is an error:

The first command prints an empty line: with no experiment set, the baseline applies. The error message names suchexp, not nosuchexp, because the parser strips a leading no before it looks the name up. The build records the setting in the binary, so you can see afterwards how it was built, and each enabled experiment also becomes a build tag goexperiment.<name>:

The experiments that exist in go1.27.2, taken from the toolchain’s own internal/goexperiment flags:

Experiments come and go quickly. In Go 1.27 the goroutine leak profile graduated and its goroutineleakprofile flag was deleted; jsonv2, greenteagc and sizespecializedmalloc moved from opt-in to baseline. The Go 1.27 release notes are the reference for what is experimental in a given release: the new simd package and simd/archsimd need GOEXPERIMENT=simd.

Source: Go 1.27 release notes, cmd/go: Environment variables and internal/goexperiment

Go telemetry lets the Go team measure how the toolchain performs and is used, in a design aimed at transparency. It applies to programs maintained by the Go team, such as the go command, gopls and govulncheck, and not to programs you build.

The behavior is controlled by one value, the mode, which is local by default: data is collected and kept on the local computer but never uploaded.

go env GOTELEMETRY reports the mode and go env GOTELEMETRYDIR the directory with configuration and counter files, both read-only. The setting is per user and has no effect on the programs you compile.

Source: Go Telemetry

New releases drop support for old operating systems, and microarchitecture variables let you raise the baseline of your own binaries. The official minimums, from the Go wiki, at the time of writing:

go tool dist list lists every supported GOOS/GOARCH pair (47 in go1.27.2). The compiler can also target a minimum microarchitecture level, trading portability for speed, with environment variables read by go build:

The build cache understands these variables, so changing one needs no cleanup. The deeper treatment of cross-compilation, build constraints and the GOOS/GOARCH matrix is in The go Command, Builds and Cross-Compilation.

Source: Go Wiki: Minimum Requirements and Go 1.27 release notes: Darwin

Both books predate everything on this page apart from the compatibility promise: