}

go mod tidy Explained: Clean Up Go Module Dependencies (2026)

Last updated: 5 min read

go mod tidy Explained: Clean Up Go Module Dependencies (2026)

go mod tidy reads your Go source files, adds any missing require directives to go.mod, removes any require entries that are no longer needed, and updates go.sum to match. Run it after adding or removing imports, or before committing code.

go mod tidy

No flags are required for normal use. The command is safe to run repeatedly — it is idempotent.

Last updated: March 2026

What Are go.mod and go.sum?

go.mod

go.mod is the manifest for your module. It declares:

  • The module path (module github.com/you/yourproject)
  • The minimum Go version required (go 1.22)
  • Direct dependencies and their minimum versions (require)
  • Replaced or excluded versions (replace, exclude)
module github.com/example/myapp

go 1.22

require (
    github.com/gin-gonic/gin v1.9.1
    golang.org/x/text v0.14.0
)

go.sum

go.sum is a lock file. It records the expected cryptographic hashes (SHA-256) of every module zip file and go.mod file that your build depends on — direct and indirect. Go verifies these hashes on every download to detect tampering.

github.com/gin-gonic/gin v1.9.1 h1:4idEAncQnU5cB7BeOkPtxjfCSye0AAm1R0RVIqJ+Jmg=
github.com/gin-gonic/gin v1.9.1/go.mod h1:hPzmOoM6Q/09Mo/pNMl0ukADapTHkI2mCU55oXI9jjA=

You should commit both go.mod and go.sum to version control. Never edit go.sum by hand.

What go mod tidy Does — Step by Step

  1. Parses all .go source files in the module (including test files)
  2. Builds the full import graph — every package imported, transitively
  3. Adds missing require entries in go.mod for any imported package not already listed
  4. Removes stale require entries for packages that are no longer imported anywhere
  5. Updates go.sum — adds hashes for new dependencies, removes hashes for removed ones
  6. Promotes indirect dependencies when a direct dependency has been removed and an indirect one becomes directly used

Before tidy

require (
    github.com/gin-gonic/gin v1.9.1
    github.com/old/unused v0.1.0    // no longer imported
)

After tidy

require (
    github.com/gin-gonic/gin v1.9.1
    // old/unused removed
)

When to Run go mod tidy

  • After go get-ing a new dependency
  • After deleting code that used a dependency
  • After upgrading Go versions
  • Before opening a pull request
  • After cloning a repo where go.sum may be out of date
  • In CI to verify the module graph is consistent

go mod download

Downloads all module dependencies listed in go.mod to the local module cache ($GOPATH/pkg/mod) without building anything.

go mod download

Useful in Docker builds to cache the download step separately from the compile step:

COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build ./...

To download a specific module:

go mod download github.com/gin-gonic/[email protected]

go mod verify

Checks that the local cached copies of downloaded modules match the hashes in go.sum. Use this to detect corruption or tampering after a download.

go mod verify
# all modules verified

If verification fails:

github.com/some/module v1.2.3: zip has been modified

Fix by clearing the module cache and re-downloading:

go clean -modcache
go mod download

The -e Flag: Continue Past Errors

By default, go mod tidy stops on the first error (unresolvable import, network failure, etc.). The -e flag tells it to proceed despite errors, doing as much as it can:

go mod tidy -e

This is useful in CI environments with restricted network access or when you want to see all missing dependencies at once rather than fixing them one at a time.

Vendor Directory: go mod vendor

The vendor directory is a local copy of all dependencies stored inside your repository. Teams working in air-gapped environments or wanting reproducible builds without relying on the module proxy use it.

go mod vendor

This creates (or updates) a vendor/ directory containing the source of every dependency. Build with the vendor directory:

go build -mod=vendor ./...
go test -mod=vendor ./...

After go mod tidy, always re-run go mod vendor if you maintain a vendor directory, otherwise the vendored code will be out of sync.

To check the vendor directory is consistent:

go mod vendor -v   # verbose: prints each vendored module

Common Errors After Running go mod tidy

Missing package after tidy removes a dependency

cannot find package "github.com/old/pkg/subpkg"

Cause: go mod tidy removed a dependency because no .go file imports it, but a build tag or test file that was excluded from the scan still needs it.

Fix: Add the import explicitly, or ensure build-tagged files are included when running tidy:

GOFLAGS=-tags=integration go mod tidy

Version conflict: go mod tidy upgrades an indirect dependency

go: github.com/indirect/[email protected]: missing go.sum entry

Fix:

go mod tidy   # regenerates go.sum
# or specifically:
go get github.com/indirect/[email protected]

go.sum out of date in CI

verifying github.com/foo/[email protected]: checksum mismatch

Fix: Run go mod tidy locally, commit both go.mod and go.sum, then push.

Go toolchain version mismatch

If your go.mod declares a go version newer than the installed toolchain, you may see:

note: module requires Go 1.22

See the Golang compile version does not match go tool version article for how to resolve Go version mismatches.

Complete Workflow Example

# 1. Add a new dependency
go get github.com/spf13/cobra@latest

# 2. Use it in your code
# import "github.com/spf13/cobra"

# 3. Tidy up (adds cobra, removes anything now unused)
go mod tidy

# 4. Update vendor directory if you use one
go mod vendor

# 5. Verify everything
go mod verify

# 6. Build and test
go build ./...
go test ./...

# 7. Commit
git add go.mod go.sum vendor/
git commit -m "add cobra dependency"

Quick Reference

Command What it does
go mod tidy Add missing, remove unused dependencies
go mod tidy -e Tidy, continuing past errors
go mod download Download dependencies to cache
go mod verify Verify cached downloads match go.sum
go mod vendor Copy dependencies into ./vendor
go mod graph Print the full module dependency graph
go mod why pkg Explain why a package is a dependency
go list -m all List all modules in the build

Related Pages

go