go mod tidy: Usage, Options & Common CI Errors

Make go.mod and go.sum match what your code actually imports.

go mod tidy ensures go.mod lists every module the build needs and nothing it does not, and that go.sum has the necessary checksums. CI commonly verifies the files are already tidy.

What it does

Scans all imports (including tests), adds missing requirements, removes unused ones, and updates go.sum. It can also set the module’s Go version with -go.

Common usage

go mod tidy                       # tidy go.mod and go.sum
go mod tidy -go=1.22              # set the go directive version
# CI gate: fail if tidy would change anything
go mod tidy && git diff --exit-code go.mod go.sum

Common CI error: go.mod is not tidy

A build fails with "missing go.sum entry for module ...; to add it: go mod download" or the CI tidy-check diff is non-empty, because a contributor changed imports without running tidy. Fix: run go mod tidy locally and commit the updated go.mod and go.sum.

Options

Related guides