The go line in go.mod is the minimum Go version your module needs. Since Go 1.21 it is mandatory, and toolchains refuse to load a module that needs a newer version. The toolchain line is a suggestion for which toolchain to use, and it matters only for the main module.
The go line
From the Go reference:
- Before Go 1.21 the directive was advisory. Now it is a mandatory requirement.
- At most one go line is allowed in a go.mod file.
- If it is missing,
go 1.16is assumed. - At
go 1.21or higher, your go line must be at least as high as the go line of every dependency.
That last rule has a consequence: adding a dependency that needs a newer Go raises your own minimum.
The toolchain line
- It is a suggested Go toolchain.
- It cannot be lower than the required Go version.
- It has an effect only when the module is the main module and the default toolchain is older than the suggestion.
- If omitted, it is implicitly
toolchain goplus the go line version. toolchain defaultdisables updating beyond theGOTOOLCHAINname.
Example:
go 1.21.0
toolchain go1.21.3
Side by side
| go line | toolchain line | |
|---|---|---|
| Role | Minimum language and module version | Preferred toolchain |
| Mandatory | Yes, since Go 1.21 | No |
| Applies in dependencies | Yes, must be consistent | No, main module only |
| Change with | go get go@1.22.1 | go get toolchain@1.24rc1 |
You can remove a toolchain line with go get toolchain@none.
Why it is a security topic
The compiler and standard library ship security fixes in patch releases. If your toolchain is behind, binaries you build carry old library code. If your go line requires a patch release that contains fixes, builds on older toolchains are blocked or switched, which is useful. A toolchain line can set a floor your team agrees on.
But with default settings the go command can download a different toolchain on a developer machine or CI runner. See what GOTOOLCHAIN does.
Steps to manage both
- Decide the oldest Go release your module supports and set the go line accordingly.
- Set the toolchain line to the current patch release you test with.
- Update both on a schedule, and whenever the Go team ships a security release.
- In CI, pin the toolchain in the build image and use
GOTOOLCHAIN=local. - Review any pull request that changes either line, since it changes the compiler.
Where Safeguard fits
Safeguard's dependency scanning and policy gates cover the modules your build resolves, and a free scan can show your current inventory.
Quick check
Can the toolchain line be older than the go line?
No. It cannot be less than the required Go version.
Does a dependency's toolchain line affect my build?
No. It only has an effect when that module is the main module.
Sources
Last reviewed: 19 October 2026.
