How to Clean Up Go Dependencies with go mod tidy

In this tutorial, you'll learn about How to Clean Up Go Dependencies with go mod tidy. We cover key concepts, practical examples, and best practices.

The Problem

Your Go project's go.mod file contains dependencies that are no longer imported, or missing dependencies that cause build failures. The go.mod and go.sum files are out of sync with the actual imports in your code.

Quick Fix

Step 1: Check the current state

cat go.mod

Expected:

module myapp

go 1.22

require (
    github.com/gorilla/mux v1.8.1
    github.com/lib/pq v1.10.9
)

Step 2: Run go mod tidy

go mod tidy

Expected output (if changes are made):

go: downloading github.com/gorilla/mux v1.8.1
go: downloading github.com/lib/pq v1.10.9
go: finding module for package github.com/stoewer/go-strcase

If no output appears, everything is already clean.

Step 3: Verify the result

go mod tidy
cat go.mod

Expected:

module myapp

go 1.22

require (
    github.com/gorilla/mux v1.8.1
    github.com/lib/pq v1.10.9
    github.com/stoewer/go-strcase v1.3.0
)

Step 4: Check what changed

git diff go.mod go.sum

This shows exactly which dependencies were added or removed.

Step 5: Run go mod tidy with verbose output

go mod tidy -v

Expected:

unused github.com/old/dependency
added github.com/new/dependency

Step 6: Verify the build

go build ./...

Expected:

(no output, build succeeds)

Step 7: Handle replace directives

If you use replace directives in go.mod for local development:

replace github.com/mycompany/internal => ../internal

go mod tidy preserves these directives. Run go mod tidy after adding or removing any replace lines.

Step 8: Check for indirect dependencies

grep indirect go.mod

Expected:

require (
    github.com/stoewer/go-strcase v1.3.0 // indirect
)

Indirect dependencies are packages your code does not import directly but a direct dependency needs. go mod tidy manages these automatically.

Alternative Solutions

Use go mod verify to check the integrity of downloaded dependencies:

go mod verify

Expected:

all modules verified

Common Errors

go mod tidy removes a needed dependency: If a dependency is imported in a file with build tags (like //go:build linux), go mod tidy only sees it on that OS. Use go mod tidy -tags linux to include build-tagged imports.

Network timeout downloading modules: If go mod tidy hangs, set a proxy: export GOPROXY=https://proxy.golang.org,direct or use GONOSUMDB for private repositories.

go.sum checksum mismatch: If you get a checksum error, the module may have been tampered with or the go.sum is outdated. Run go mod tidy to regenerate the checksum file.

Private module not found: For private repositories, set GOPRIVATE=github.com/mycompany/* so Go does not attempt to fetch from the public proxy.

Prevention

• Run go mod tidy before every commit to keep go.mod and go.sum clean.
• Add go mod tidy to your CI pipeline to catch stale dependencies.
• Use go mod why -m <package> to understand why a dependency exists.
• Review go.mod changes during code reviews to ensure accurate dependencies.