go mod tidy, vendor, download & graph

Module maintenance commands keep go.mod honest, warm caches, vendor sources for offline builds, and visualize why one version won over another.

Summary

go mod tidy aligns require directives with imports actually referenced in your module.

go mod download fetches modules into GOMODCACHE without compiling.

go mod vendor copies required module sources into vendor/ for -mod=vendor builds.

go mod graph prints the module requirement graph MVS consumed.

Use them after dependency changes, before release branches, and when debugging version selection.

Recipe

Quick-reference recipe card - copy-paste ready.

# Normalize requires after a refactor
go mod tidy
 
# Warm module cache in CI without compiling
go mod download all
 
# Materialize sources for air-gapped or audited builds
go mod vendor
 
# Inspect requirement edges (module@version pairs)
go mod graph | head

When to reach for this:

• Run go mod tidy on every PR that adds or removes imports.
• Run go mod download as an early CI step with a cached GOMODCACHE.
• Run go mod vendor when policy requires reviewing third-party source in-repo.
• Pipe go mod graph into graph tools when explaining a surprising transitive version.

Working Example

# Start from a module that imports x/sync
go get golang.org/x/sync@v0.10.0
 
# Add an import in code, remove another, then tidy
go mod tidy
 
# Pre-fetch everything the build list needs
go mod download all
 
# Vendor for -mod=vendor CI job
go mod vendor
 
# Build using only vendor/ + stdlib
go build -mod=vendor -o bin/worker ./cmd/worker
 
# See why v0.10.0 appears
go mod graph | rg 'golang.org/x/sync'

// cmd/worker/main.go
package main
 
import (
    "fmt"
    "golang.org/x/sync/errgroup"
)
 
func main() {
    var g errgroup.Group
    g.Go(func() error { fmt.Println("task"); return nil })
    _ = g.Wait()
}

What this demonstrates:

• go get records a version; tidy prunes anything no longer imported.
• download populates GOMODCACHE for faster later compiles.
• vendor plus -mod=vendor builds without reaching module proxies.
• go mod graph helps audit edges after upgrades.

Deep Dive

How It Works

• tidy loads all packages in the module, walks imports, and rewrites go.mod require blocks to the minimal set at chosen versions.
• It also updates go.sum with hashes for direct and indirect modules retained.
• download resolves the build list and copies .zip archives into the module cache; no .a files are built.
• vendor repeats download then extracts sources under vendor/<module>/, rewriting go.mod with an optional go mod vendor comment marker.

Command Reference

Vendor Workflow

# Typical regulated pipeline
go mod tidy
go mod vendor
git add go.mod go.sum vendor/
go test -mod=vendor ./...

Graph and Why

# Explain a selected version
go mod why -m golang.org/x/sync
 
# JSON module list for SBOM tooling
go list -m -json all

Gotchas

• Committing tidy without tests - pruned requires may hide broken builds in unused packages. Fix: go test ./... after every tidy.
• Vendor drift - editing go.mod without re-vendoring breaks -mod=vendor CI. Fix: automate go mod vendor in the same commit as dependency bumps.
• Huge vendor/ trees in libraries - consumers rarely want your copies. Fix: vendor in applications; publish libraries without vendor/ unless policy demands.
• Assuming download compiles - it only fetches zips; compile errors appear later at go build. Fix: follow download with go test in CI.
• Ignoring go mod verify failures - indicates cache tampering or incomplete go.sum. Fix: investigate proxy mirrors; do not delete sums blindly.
• Indirect noise in go.mod - Go 1.17+ marks indirect requires; tidy keeps ones needed for MVS. Fix: trust tidy; use go mod why instead of hand-editing.

Alternatives

FAQs

Related

• The go Command: Build, Test, and Module Lifecycle - MVS and build list
• Go Toolchain Basics - first go mod tidy example
• Cross-Compilation & Private Module Proxies - GOPRIVATE and proxies
• go build, run, install & clean - -mod=vendor builds
• Go Toolchain Best Practices - dependency hygiene in CI

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).