TL;DR
Go.sum is a local cache of module checksums, not a lockfile, and it does not affect version selection. For dependency resolution and graph analysis, rely on go.mod and Go tooling that reads it.
What happened
A widely circulated clarification argues that go.sum should not be treated as a lockfile or used for dependency-graph analysis. The file is essentially a local mapping of module versions to cryptographic hashes used to validate module contents against the Go Checksum Database; entries may refer to versions that aren’t actually used, so go.sum has no semantic role in choosing versions. The author notes that go.sum was not part of the original modules design by default because it does not change build outcomes, and its purpose is strictly to strengthen supply-chain security by making checksum verification local and reproducible. By contrast, go.mod contains the exact versions used to build the main module (including transitive dependencies since Go 1.17) and therefore is the authoritative source for resolution. The post recommends parsing go.mod with the official modfile package, using go mod edit -json, or following the file specification rather than inspecting go.sum.
Why it matters
- go.sum entries do not determine which module versions are used; relying on it for graphs can produce incorrect results.
- go.sum’s role is security-focused: it ties module versions to checksums for verification, not version selection.
- go.mod functions as both manifest and lockfile for the main module, listing exact versions including transitive deps (since Go 1.17).
- Tooling and audits that need accurate resolution should read go.mod or use Go commands, not parse go.sum.
Key facts
- go.sum is a local cache mapping module versions to cryptographic hashes for the Go Checksum Database.
- Entries in go.sum may refer to versions that are not part of the build; they do not affect version resolution.
- go.sum was not enabled by default in the initial modules design because it has no observable effect on builds.
- The primary purpose of go.sum is security: to make checksum verification against the Checksum Database local and self-contained.
- go.mod lists the precise versions used to build the main module and, since Go 1.17, includes required transitive dependencies for the module and its tests.
- Recommended ways to consume go.mod programmatically are golang.org/x/mod/modfile, go mod edit -json, or parsing according to the go.mod specification.
- All go commands accept a -mod flag: when set to 'mod', missing deps can be added automatically; when 'readonly', such changes are errors.
- go mod tidy and, effectively, go get default to mod; most other go commands default to readonly.
- go list -m all prints the entire module graph including modules not contributing to the build; alternative go list invocations may reflect local build constraints.
What to watch next
- An open proposal exists to add a flag to go list that would perform resolution consistent with go.mod (confirmed in the source).
- Whether third-party tools and ecosystems will stop parsing go.sum for dependency graphs: not confirmed in the source.
Quick glossary
- go.sum: A file that records cryptographic hashes for specific module versions, used to verify module content against the Go Checksum Database.
- go.mod: The module manifest that lists required modules and the exact versions used to build the main module; also acts as the lockfile for that module.
- Go Checksum Database: A service that helps ensure a given module version corresponds to a stable, verifiable set of source contents across the ecosystem.
- lockfile: A file used in some ecosystems to record the exact dependency versions selected during a build to ensure reproducible installs.
Reader FAQ
Is go.sum a lockfile?
No. go.sum is a checksum cache and does not control version resolution.
Which file should I parse to analyze dependency versions?
go.mod is the authoritative source for the versions used to build the main module.
How can I programmatically read go.mod?
Use golang.org/x/mod/modfile, run go mod edit -json, or parse it per the go.mod specification.
Does go.sum affect builds or dependency selection?
No. go.sum has zero semantic effect on version resolution; its role is verification against the checksum database.
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
- An entry in go.sum does not represent a dependency #4740
- Incorrect usage of go.sum in go dependency scanning
Related posts
- Lean 4 proof argues SSOT needs definition-time hooks and introspection
- Go authors: stop treating go.sum as a lockfile — use go.mod instead
- Open Infrastructure Map: Layered visualization of power, pipelines, and telecoms