Go modules: go.mod, go.sum and the major version suffix

What it is

The Go Modules Reference defines a module as a collection of packages released together, with a go.mod file at its root naming the module path, the go directive (the minimum Go version, enforced rather than advisory since Go 1.21), require lines and optional replace, exclude, retract and toolchain directives. Versions follow Semantic Versioning 2.0.0 with a v prefix. The reference describes minimal version selection: the go command traverses the requirement graph and builds with the highest version each module is required at; it never picks a newer release just because one exists, so the build list is reproducible from go.mod alone. go.sum records cryptographic hashes of every module used, checked on download and, by default, against the public checksum database sum.golang.org.

The rule newcomers stumble over is the major version suffix. The reference states the import compatibility rule (if an old package and a new package have the same import path, the new package must be backwards compatible with the old package) and therefore requires that major version 2 and above carry the suffix in the module path: example.com/lib/v2. Versions v0 and v1 carry no suffix; v0 has no compatibility promise. Tags of v2 or higher without a go.mod file appear with +incompatible.

Why it matters

pip and npm prefer the newest allowed version and need a lock or pin file for reproducibility; Go resolves to the lowest that satisfies everyone and recomputes the same list on every command. Because lib and lib/v2 are different import paths, both may coexist in the same build, and upgrading a major version is a search-and-replace of imports rather than a resolver conflict.

How to apply

• Run go mod tidy after changing imports; it adds missing requirements, drops unused ones and updates go.sum; commit both files.
• Upgrade one dependency with go get example.com/lib@v1.4.0; move to a new major by importing the suffixed path.
• When publishing v2 of your own module, change the module line to end in /v2 before tagging; the blog on v2 modules recommends a major version subdirectory (v2/go.mod) over separate branches.
• Use replace only in the main module for local development; the reference states it is ignored in other modules' go.mod files.
• Prefer retract over deleting a bad tag; the tag stays in the checksum database.

Pitfalls

Tagging v2.0.0 on a module whose path lacks the suffix makes the go command reject the version. The go directive is a hard requirement since Go 1.21: a toolchain older than the declared version switches to a newer one or refuses to build, rather than warning. go.sum is not a lock file: it verifies what minimal version selection chose.