rgoussu.dev
rgoussu@goussu: ~/library/go/toolchain
❯ ~/library/go/toolchain cat go-mod.md

go mod

# The daily dependency interface — init, tidy, download, why, graph, vendor, edit — over go.mod and go.sum.

Conceptsaved 2026-08-09updated 2026-08-20 #go#tooling#build#dependencies

Overview

go mod is the command-level face of Go modules: a handful of subcommands that keep go.mod (requirements) and go.sum (cryptographic checksums) in sync with what the code actually imports. The deeper machinery — minimal version selection, the module proxy, the checksum database — is covered in Go modules; this note is the muscle memory.

Key points

  • go mod init example.com/mod: creates go.mod with the module path — the import prefix for every package in the module.
  • go mod tidy: the one you run constantly — adds missing requirements, drops unused ones, updates go.sum. Run it before every commit that touches imports; CI checking git diff --exit-code go.mod go.sum after tidy is a common gate.
  • go mod download: pre-fills the module cache (GOPATH/pkg/mod) — Docker layer caching's best friend (COPY go.mod go.sum + download before copying source).
  • go mod why -m <module>: shows the import chain explaining why a dependency exists; go mod graph dumps the full requirement graph for scripting.
  • go mod vendor: materializes dependencies into vendor/ for hermetic builds (-mod=vendor); mostly for locked-down CI or corporate environments — the module cache plus checksums usually suffice.
  • go mod edit: scripted edits (-replace, -require, -go) — the mechanical tool; humans mostly edit go.mod directly.
  • go.mod also carries the toolchain: the go line sets the minimum language version and the optional toolchain go1.x.y line names the toolchain to switch to when the local one is older. Both are floors, not pins — see The Go toolchain. Note that this makes go.mod a file the project owns and a provisioning file at once, so tooling that maintains it must merge the one directive in place rather than render the file.
  • go.sum is not a lock file: go.mod already pins versions (MVS is deterministic); go.sum holds hashes so a tampered or republished module fails the build. Commit both.
  • Adding a dependency is implicit: go get example.com/pkg@v1.2.3 (or just importing it and running tidy); go get -u ./... upgrades.

Examples

go mod init github.com/rgoussu/widget
go get github.com/jackc/pgx/v5@latest
go mod tidy
go mod why -m golang.org/x/crypto

Related

  • The Go toolchain — parent catalog.
  • Go modules — MVS, proxy protocol, and sumdb behind these commands.
  • go work — the workspace answer to cross-module local development.
  • Build ecosystem (Java) — the Maven/Gradle world this replaces with one built-in subcommand.
  • Version managers — why Go's built-in mechanism means the ecosystem needs no manager of its own.