go mod tidy: add missing and remove unused Go module dependencies
- tool
- Go
- versions
- Go 1.11+, -diff: Go 1.23+
- os
- any
go mod tidy makes go.mod and go.sum match the source code of your module: it adds a require line for every imported package whose module is missing, removes requirements that no package imports any more, and adds the checksums the build needs to go.sum. Run it from the module root after adding or removing imports, and before committing.
Typical use
go mod init example.com/hello
# write main.go that imports "rsc.io/quote"
go mod tidy
go run .The reference documentation describes the steps: it loads every package in the main module and everything they import, recursively, including packages imported by tests; adds a requirement on the latest version of each module that provides a missing package; removes require lines for modules that provide none of those packages; and adds or removes go.sum entries to match. It may also add or remove // indirect comments. While it downloads, it reports the modules it looks up and finds on standard error.
Options
| Command | What it does |
|---|---|
| go mod tidy | Add missing requirements, remove unused ones, update go.sum |
| go mod tidy -v | Print the modules it removes to standard error |
| go mod tidy -e | Keep going despite errors loading packages |
| go mod tidy -diff | Change nothing; print the needed changes as a diff and exit non-zero if any (Go 1.23+) |
| go mod tidy -go=1.22 | Set the go directive to that version and tidy for it |
| go mod tidy -compat=1.21 | Check that Go 1.21 would select the same module versions (default: the version before the go directive) |
| go mod tidy -x | Print the commands tidy executes |
Pitfalls
- Run it at the module root. Outside a module it fails with go.mod file not found; in a subfolder it works on the nearest
go.modabove, which may be another module in a multi-module repository. - All platforms count. tidy acts as if all build tags are enabled (except
ignore), so a dependency imported only in a_windows.gofile or behind a custom tag is kept, even on Linux. Packages intestdataor in folders starting with.or_are not considered. - Tests count too. Modules imported only by
_test.gofiles stay ingo.mod. - Private modules. Fetching a private repository needs
GOPRIVATE(orGONOSUMDB/GOPROXYsettings) so the command does not ask the public proxy and checksum database for it. - Unused imports in code do not keep a dependency alive; the compiler rejects them anyway with imported and not used.
- Network access. Missing modules are downloaded from
GOPROXY(by defaultproxy.golang.org). In CI without network, run tidy beforehand and commit the result, or use a module cache or vendor directory.
Use it in CI
go mod tidy -diff (Go 1.23+) is the cleanest check that a pull request committed tidy files: it exits non-zero and prints the diff when go.mod or go.sum is out of date. On older Go versions, run go mod tidy followed by git diff --exit-code go.mod go.sum.
Confirm it worked
go build ./... and go test ./... succeed without "missing go.sum entry" messages, and running go mod tidy a second time changes nothing (git status shows no modified go.mod or go.sum).
FAQ
What is the difference between go get and go mod tidy?
go get adds, upgrades or downgrades a specific module to the version you name. go mod tidy does not upgrade anything on purpose: it makes go.mod and go.sum match the imports in your code, adding what is missing and dropping what is unused.
Should I commit go.sum?
Yes. go.sum holds the expected checksums of every module version the build needs. Commit it together with go.mod so other machines and CI verify the same downloads.
Why did go mod tidy add // indirect comments?
A module marked indirect is needed by the build but not imported directly by any package in your module, usually because a dependency needs it. Since Go 1.17 these are listed in go.mod so the module graph can be pruned.