Versions, minimal version selection and go.sum

A module is a directory with a go.mod file: a module path, a Go version and the requirements the build needs. Versions are semantic and the path carries the major one from v2 onwards, so example.com/lib/v2 and example.com/lib are different modules. The modules lesson created a module; this one explains what the version lines mean and how one is chosen.

A requirement and its checksum

The import of testify/assert in the program is what makes the module a dependency: go mod tidy adds a require line and the checksums to go.sum. The sum file records the hash of the module archive and of its go.mod, so a download that does not match is refused, which is what protects a build from a replaced or tampered proxy.

package main import ( "fmt" "github.com/stretchr/testify/assert" ) func main() { fmt.Println(assert.ObjectsAreEqual(1, 1)) }

go mod tidy && cat go.mod

module example.com/demo

go 1.26

require github.com/stretchr/testify v1.12.1

require go.yaml.in/yaml/v3 v3.0.5 // indirect

head -4 go.sum

github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE=
github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg=
go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw=
go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg=

go list -m all

example.com/demo
github.com/stretchr/objx v0.5.3
github.com/stretchr/testify v1.12.1
go.yaml.in/yaml/v3 v3.0.5

The require line names one exact version and the sum file has two lines per module, one for the archive and one for the go.mod. go list -m all prints the build list: the main module first, then every module the build would use, each with the version that was selected. The indirect entries are dependencies of dependencies that the main module does not import directly.

Minimal version selection

When two requirements ask for different versions of the same module, Go does not fetch the newest; it takes the highest version anyone asked for, which is the minimal version that satisfies every requirement. That is why a build is reproducible without a lock file: the go.mod of every module in the graph pins its own requirements, and the selection is a pure function of them. Adding a requirement never downgrades another; removing one may lower the selected version.

go mod why -m github.com/stretchr/testify

# github.com/stretchr/testify
example.com/demo
github.com/stretchr/testify/assert

go list -m -versions github.com/stretchr/testify | cut -c1-110

github.com/stretchr/testify v1.1.1 v1.1.2 v1.1.3 v1.1.4 v1.2.0 v1.2.1 v1.2.2 v1.2.3 v1.3.0 v1.4.0 v1.5.0 v1.5.

go mod why walks the import graph backwards and names the package that pulled the module in, which is the question a reviewer asks about an unexpected requirement. go list -m -versions lists what the proxy offers, and it is only for reading: the build never picks from that list on its own.

What go get changes

go get module@version edits the requirement and leaves the files to the next build; since Go 1.17 it no longer installs a command. go get module@latest is the explicit upgrade, and go get -u ./... upgrades the dependencies of the packages in the current module. Each of these writes go.mod and go.sum, and the diff of those two files is what a review of a dependency change reads.

A version in go.mod can be a pseudo-version such as v1.2.4-0.20260101120000-abcdef123456 when the dependency is a commit rather than a tag: the timestamp and the commit hash make it unique and ordered. A branch name is not a version, so a requirement always names a specific build, which is the property the whole scheme rests on.

Exercises

  1. Add a second dependency and run go mod why for it. Which import pulled it in?
  2. Delete a line from go.sum and run go build. What does the toolchain do, and what does it refuse to do?
  3. Find a module at v2 and compare its import path with the v1 path. What would a build do if the path kept the v1 name?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does a go.mod require line pin?

    Answer

    One exact module version

    The build list is computed from exact requirements.

  2. What does minimal version selection choose?

    Answer

    The highest version any requirement asks for

    MVS takes the maximum of the required minimums, so builds are reproducible.

  3. What does go.sum contain?

    Answer

    Checksums of module archives and their go.mod files

    A mismatch is refused, which protects the build from a tampered download.

  4. What does go list -m all print?

    Answer

    The build list with the selected version of every module

    It is the resolved graph, not the catalogue.

  5. What does go mod why answer?

    Answer

    Which import path pulled a module into the build

    It walks the import graph backwards to the main module.

  6. How is a v2 module imported?

    Answer

    With /v2 at the end of its path

    Semantic import versioning puts the major version in the path.

  7. What does go get module@latest do?

    Answer

    Upgrades the requirement and rewrites go.mod and go.sum

    Since Go 1.17 go get edits requirements; go install builds commands.

  8. What is a pseudo-version?

    Answer

    A version derived from a commit timestamp and hash

    It names an exact commit that is not tagged.

  9. Why does the build not need a lock file?

    Answer

    Every module pins its own requirements and the selection is deterministic

    The go.mod files of the graph are the lock; go.sum verifies the content.

  10. What happens when a checksum does not match go.sum?

    Answer

    The build stops with a security error

    A mismatch means the content is not what was reviewed.

The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev