go mod tidy

When working with Go modules, keeping dependencies up-to-date while maintaining a clean go.mod file can be confusing. Different commands produce varying results, leaving developers unsure which approach is correct.

Problem: Inconsistent Go Module Updates

The core issue stems from how Go's module commands interact with dependency management. Running different sequences of commands (go get -u, go mod tidy, or their combinations) results in go.mod files with different numbers of lines and dependencies.

This happens because:

• go get -u aggressively pulls in dependencies and their latest compatible versions
• go mod tidy prunes unnecessary dependencies to match actual source code requirements
• Module maintainers may not have optimized their go.mod files initially

Recommended Solution

The optimal approach for updating all dependencies in a Go module is:

go get -u ./...
go mod tidy

This combination ensures you get the latest compatible versions of all dependencies while maintaining a clean, minimal go.mod file.

INFO

For Go 1.16 and later, use go get -u ./... instead of just go get -u to recursively update all packages in your project

Command Variations Explained

Basic Update Commands

// Updates current package only
go get -u

// Updates all packages recursively (recommended)
go get -u ./...

// Updates specific package(s)
go get -u example.com/package

// Updates to specific version
go get -u example.com/package@v1.2.3

Cleanup Commands

// Prunes unnecessary dependencies
go mod tidy

// Downloads modules to local cache (without building)
go mod download

Why the Two-Step Process?

1. go get -u ./... updates all dependencies to their latest compatible versions
2. go mod tidy removes any dependencies that aren't actually needed by your code

WARNING

Using go get -u alone may leave unnecessary dependencies in your go.mod file, while using only go mod tidy won't update to newer versions

Advanced Options

Update Including Test Dependencies

go get -t -u ./...

DANGER

This pulls in test dependencies which may significantly increase your module size—only use if specifically needed

Interactive Updates

For a more visual approach, consider using go-mod-upgrade, an interactive tool that highlights patch updates (yellow) and breaking changes (red).

Understanding go.mod Changes

Since Go 1.17, indirect dependencies are organized in a separate require block in go.mod. This structural change means line count comparisons between different Go versions may not be meaningful.

The go.sum file may grow after running go mod tidy as it adds checksums for all necessary dependencies, even if the go.mod file becomes smaller.

Best Practices

1. Always run go mod tidy after updating dependencies
2. Use go get -u ./... rather than go get -u for complete project updates
3. Commit both go.mod and go.sum to version control
4. Test thoroughly after updates to ensure compatibility

TIP

Run your test suite after updating dependencies to catch any breaking changes introduced by new versions:

go test ./...

By following the go get -u ./... && go mod tidy pattern, you ensure your project uses the latest compatible dependencies while maintaining a clean, minimal module definition that accurately reflects your project's actual requirements.