TL;DR
The author argues go.sum is not a lockfile and has no effect on version resolution; it is a local cache of checksums for the Go Checksum Database used for security. For dependency versions and resolution you should read go.mod (which, since Go 1.17, records all transitive deps for builds and tests).
What happened
A developer note clarifies that go.sum should not be used as a source of truth for dependency graphs or version resolution. The file simply maps module versions to cryptographic hashes and functions as a local cache of entries from the Go Checksum Database; whether an entry appears in go.sum does not change package resolution or the versions the toolchain selects. The author points out that go.sum was not enabled by default in the original modules design because it produces no observable build effects—its role is security, not semantics. By contrast, go.mod contains the exact versions used to build the main module and, since Go 1.17, has included all transitive dependencies required for building the module and its tests. The post recommends parsing go.mod via the official golang.org/x/mod/modfile package, using go mod edit -json, or following the go.mod specification rather than inspecting go.sum.
Why it matters
- Misreading go.sum can lead tools or people to draw incorrect conclusions about which modules actually affect a build.
- go.sum’s purpose is to strengthen supply-chain security by recording checksums, not to pin or resolve versions.
- go.mod is the authoritative source for the versions used to build a module, including transitive dependencies since Go 1.17.
- Using the correct files and APIs prevents unnecessary complexity and avoids relying on a file with zero semantic effect.
Key facts
- go.sum is a local cache mapping module versions to cryptographic hashes tied to the Go Checksum Database.
- Entries in go.sum may refer to versions that are not used for the current build; presence in go.sum does not affect resolution.
- go.sum was not enabled by default in the original modules design because it does not change build behavior.
- The Checksum Database provides an ecosystem-wide guarantee about module contents; go.sum makes that guarantee available locally.
- go.mod lists the exact versions used to build the main module and, since Go 1.17 (August 2021), includes transitive dependencies required for builds and tests.
- You can programmatically read go.mod with golang.org/x/mod/modfile or by running go mod edit -json, or parse it per its specification.
- All go commands accept a -mod flag: setting -mod=mod allows automatic additions to go.mod, while -mod=readonly treats such changes as errors.
- go mod tidy and go get (effectively) default to -mod=mod; other go commands default to -mod=readonly.
- Different major versions in Go are treated as distinct modules; semantic versioning assumptions are applied and go.mod serves manifest and lock roles.
What to watch next
- An open proposal exists to add a go list flag that would perform go.mod-like resolution instead of emitting the entire module graph.
- not confirmed in the source
- not confirmed in the source
Quick glossary
- go.sum: A file that records cryptographic checksums for module versions; used to verify module contents locally against the Go Checksum Database.
- go.mod: The module manifest that lists dependency module paths and the exact versions used to build the main module.
- Go Checksum Database: A service that publishes cryptographic hashes of module versions so that clients can verify consistent module contents across downloads.
- lockfile: A file, common in many ecosystems, that records the precise dependency versions used in a particular build to ensure reproducible installs.
- semantic versioning: A versioning scheme that conveys compatibility through a MAJOR.MINOR.PATCH format, often used to infer upgrade compatibility rules.
Reader FAQ
Is go.sum a lockfile?
No. go.sum stores checksums and has no semantic effect on version resolution.
Which file shows the versions used to build a module?
go.mod is the authoritative file for the exact versions used to build the main module; since Go 1.17 it includes necessary transitive deps for builds and tests.
Should tools parse go.sum to construct dependency graphs?
No — the author recommends against parsing go.sum for dependency graphs; use go.mod instead.
How can I programmatically read go.mod?
Use golang.org/x/mod/modfile, run go mod edit -json, or parse it according to the go.mod specification.
Does go.sum improve security?
Yes. Its role is to tighten the security story by linking local verification to the Checksum Database; it does not change build behavior.
5 Jan 2026 GO.SUM IS NOT A LOCKFILE I need everyone to stop looking at go.sum, especially to analyze dependency graphs. It is not a “lockfile,” and it has zero…
Sources
- go.sum Is Not a Lockfile
- go.sum Is Not a Lockfile | Lobsters
- Why You Must Commit go.mod and go.sum Files in Go …
- An entry in go.sum does not represent a dependency #4740
Related posts
- Open Infrastructure Map: Layered visualization of power, pipelines, and telecoms
- IceRaidsNearMe offers real-time, crowdsourced map of immigration enforcement
- How to Push Back Against Biometric Surveillance at Wegmans and Protect Privacy