Golang Dependency Management

Persona: You are a Go dependency steward. You treat every new dependency as a long-term maintenance commitment — you ask whether the standard library already solves the problem before reaching for an external package.

Dependencies:

• govulncheck: go install golang.org/x/vuln/cmd/govulncheck@latest

Go Dependency Management

AI Agent Rule: Ask Before Adding Dependencies

Before running `go get` to add any new dependency, AI agents MUST ask the user for confirmation. AI agents can suggest packages that are unmaintained, low-quality, or unnecessary when the standard library already provides equivalent functionality. Using go get -u to upgrade an existing dependency is safe.

Before proposing a dependency, evaluate:

• Does the standard library already cover the use case?
• Is the license compatible?
• Are there well-known alternatives?
• What it does and why it's needed?

The samber/cc-skills-golang@golang-popular-libraries skill contains a curated list of vetted, production-ready libraries. Prefer recommending packages from that list. When no vetted option exists, favor well-known packages from the Go team (golang.org/x/...) or established organizations over obscure alternatives.

Key Rules

• go.sum MUST be committed — it records cryptographic checksums of every dependency version, letting go mod verify detect supply-chain tampering. Without it, a compromised proxy could silently substitute malicious code
• govulncheck ./... or go tool govulncheck ./... before every release — catches known CVEs in your dependency tree before they reach production
• Maintenance status, license compatibility, and stdlib alternatives are important considerations before adding a dependency — every dependency increases attack surface, maintenance burden, and binary size
• go mod tidy before every commit that changes dependencies — removes unused modules and adds missing ones, keeping go.mod honest

go.mod & go.sum

Essential Commands

Vendoring

Use go mod vendor when you need hermetic builds (no network access), reproducibility guarantees beyond checksums, or when deploying to environments without module proxy access. CI pipelines and Docker builds sometimes benefit from vendoring. Run go mod vendor after any dependency change and commit the vendor/ directory.

Installing & Upgrading Dependencies

Adding a Dependency

go get github.com/google/uuid          # Latest version
go get github.com/google/uuid@v1.6.0   # Specific version
go get github.com/google/uuid@latest   # Explicitly latest
go get github.com/google/uuid@<commit> # Specific commit (pseudo-version)

Upgrading

go get -u ./...            # Upgrade ALL direct+indirect deps to latest minor/patch
go get -u=patch ./...      # Upgrade to latest patch only (safer)
go get github.com/pkg@v1.5 # Upgrade specific package

Prefer `go get -u=patch` for routine updates. Patch and minor updates are usually lower risk than major upgrades, but still require review. For dependency updates, run:

go get -u=patch ./...
go mod tidy
go test ./...
go vet ./...
govulncheck ./...   # or: go tool govulncheck ./...

Release notes and changelogs for libraries affecting persistence, serialization, networking, authentication, authorization, cryptography, or public APIs may contain important information about breaking changes.

Removing a Dependency

go get github.com/google/uuid@none  # Mark for removal
go mod tidy                          # Clean up go.mod and go.sum

Installing CLI Tools

For Go 1.24+ modules, pin executable tools in go.mod with tool directives. Do not create a new tools.go blank-import file unless the module must support Go <1.24.

# Add tools to the current module.
go get -tool github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
go get -tool golang.org/x/vuln/cmd/govulncheck@latest
go get -tool golang.org/x/perf/cmd/benchstat@latest

# Run pinned tools reproducibly.
go tool golangci-lint run ./...
go tool govulncheck ./...
go tool benchstat old.txt new.txt

# Install all module-pinned tools into GOBIN/PATH when needed.
go install tool

# Update pinned tools deliberately, then review go.mod/go.sum.
go get -u tool
go mod tidy

go.mod shape for a module targeting Go 1.26 or newer. This is an example target, not a cap; keep the project's actual go directive and do not change it just to add tools.

```go.mod module example.com/project

go 1.26

tool ( github.com/golangci/golangci-lint/v2/cmd/golangci-lint golang.org/x/vuln/cmd/govulncheck golang.org/x/perf/cmd/benchstat )

For Go <1.24 only, use the legacy `tools.go` blank-import workaround:

//go:build tools

package tools

import ( _ "github.com/golangci/golangci-lint/v2/cmd/golangci-lint" _ "golang.org/x/vuln/cmd/govulncheck" )

Rule: Go 1.24+ = `tool` directives. Go <1.24 = `tools.go` fallback.

### Go 1.26+ module target note

When using a Go 1.26 or newer toolchain, `go mod init` may create a module with an older default `go` directive. If the project intentionally targets Go 1.26+ APIs, update the directive deliberately:

go mod edit -go=1.26 go mod tidy

For future Go versions, use the project's intended target version. Do not use APIs newer than the module's `go` directive until the project explicitly agrees to upgrade it.

## Deep Dives

- **[Versioning & MVS](./references/versioning.md)** — Semantic versioning rules (major.minor.patch), when to increment each number, pre-release versions, the Minimal Version Selection (MVS) algorithm (why you can't just pick "latest"), and major version suffix conventions (v0, v1, v2 suffixes for breaking changes).

- **[Auditing Dependencies](./references/auditing.md)** — Vulnerability scanning with `govulncheck`, tracking outdated dependencies, analyzing which dependencies make the binary large (`goweight`), and distinguishing test-only vs binary dependencies to keep `go.mod` clean.

- **[Dependency Conflicts & Resolution](./references/conflicts.md)** — Diagnosing version conflicts (what `go get` does when you request incompatible versions), resolution strategies (`replace` directives for local development, `exclude` for broken versions, `retract` for published versions that should be skipped), and workflows for conflicts across your dependency tree.

- **[Go Workspaces](./references/workspaces.md)** — `go.work` files for multi-module development (e.g., library + example application), when to use workspaces vs monorepos, and workspace best practices.

- **[Automated Dependency Updates](./references/automated-updates.md)** — Setting up Dependabot or Renovate for automatic dependency update PRs, auto-merge strategies (when to merge automatically vs require review), and handling security updates.

- **[Visualizing the Dependency Graph](./references/visualization.md)** — `go mod graph` to inspect the full dependency tree, `modgraphviz` to visualize it, and interactive tools to find which dependency chains cause bloat.

## Cross-References

- → See `samber/cc-skills-golang@golang-continuous-integration` skill for Dependabot/Renovate CI setup
- → See `samber/cc-skills-golang@golang-security` skill for vulnerability scanning with govulncheck
- → See `samber/cc-skills-golang@golang-popular-libraries` skill for vetted library recommendations

## Quick Reference

Start a new module

go mod init github.com/user/project

Add a dependency

go get github.com/google/uuid@v1.6.0

Upgrade all deps (patch only, safer)

go get -u=patch ./...

Remove unused deps

go mod tidy

Check for vulnerabilities

govulncheck ./... # or: go tool govulncheck ./...

Check for outdated deps

go list -u -m -json all | go-mod-outdated -update -direct

Analyze binary size by dependency

goweight

Understand why a dep exists

go mod why -m github.com/some/module

Visualize dependency graph

go mod graph | modgraphviz | dot -Tpng -o deps.png

Verify checksums

go mod verify

Auditing Dependencies

Test-Only vs Binary Dependencies

Go's go.mod does not distinguish between test-only and production dependencies. All modules appear together, with // indirect marking transitive dependencies.

What Gets Included in Your Binary

• *_test.go files are never compiled by go build — only by go test
• Packages imported only by test files are not linked into the final binary
• However, their modules still appear in go.mod

Module Graph Pruning (Go 1.17+)

With go 1.17 or higher in go.mod, Go prunes the module graph: transitive dependencies needed only for tests of other modules are excluded from the build graph. This reduces go.mod size and avoids downloading unnecessary modules.

Upgrading With or Without Test Dependencies

go get -u ./...       # Upgrade deps, EXCLUDING test-only deps
go get -u -t ./...    # Upgrade deps, INCLUDING test-only deps

Impact on Binary Size

To check whether a large dependency is actually linked into your binary (vs. only used in tests), use goweight or go-size-analyzer — if the package doesn't appear in the binary breakdown, it's test-only and not contributing to binary size.

Vulnerability Scanning with govulncheck

govulncheck reports known vulnerabilities that affect your code. It uses static analysis to narrow reports to vulnerabilities in code paths your project actually calls — unlike generic CVE scanners that flag every dependency regardless of usage.

# Scan source code (most common)
govulncheck ./...
# Or, when govulncheck is pinned with a Go 1.24+ tool directive:
go tool govulncheck ./...

# Scan a compiled binary
govulncheck -mode=binary ./bin/myapp

# JSON output (for CI integration)
govulncheck -format json ./...

# Include test code in analysis
govulncheck -test ./...

Output shows the vulnerability ID, affected module, fixed version, and the call trace from your code to the vulnerable function. If a vulnerability exists in a dependency but your code never calls the affected function, govulncheck does not flag it.

For CI pipeline integration, see the samber/cc-skills-golang@golang-continuous-integration skill.

Tracking Outdated Dependencies with go-mod-outdated

psampaz/go-mod-outdated lists outdated direct dependencies with available updates.

# Show outdated direct dependencies with available updates
go list -u -m -json all | go-mod-outdated -update -direct

# Fail in CI if dependencies are outdated
go list -u -m -json all | go-mod-outdated -update -direct -ci

# Markdown output
go list -u -m -json all | go-mod-outdated -update -direct -style markdown

Output columns: MODULE, CURRENT version, WANTED (latest minor/patch), LATEST (latest overall), and VALID TIMESTAMPS (warns if an "update" is chronologically older than current).

Analyzing Dependency Size with goweight

jondot/goweight lists every package linked into the binary sorted by size contribution. It helps identify bloated dependencies and evaluate whether a lighter alternative exists.

goweight          # Sort by size
goweight --json   # JSON output for CI tracking

Modern alternative: go-size-analyzer (gsa) supports ELF, Mach-O, PE, and WebAssembly formats with interactive HTML/SVG visualization:

go get -tool github.com/Zxilly/go-size-analyzer/cmd/gsa@latest
go build -o ./myapp ./cmd/myapp
go tool gsa -f html -o size-report.html ./myapp

Automated Dependency Updates

Automate minor/patch dependency updates to reduce maintenance burden and stay current with security fixes. This requires a solid CI pipeline — tests and linting must pass before any auto-merge.

Dependabot vs Renovate

Renovate is generally more mature and configurable. Dependabot is simpler to set up for GitHub-only projects.

Auto-Merge Strategy

• Minor and patch updates: Auto-merge only after CI passes (tests + lint + govulncheck) and the package is low-risk for the project
• Major updates: Create PR for manual review (may contain breaking changes)
• Security updates: Auto-merge regardless of version bump type

For workflow configuration files (dependabot.yml, renovate.json, auto-merge workflows), see the samber/cc-skills-golang@golang-continuous-integration skill.

Update Verification

Before committing a dependency update:

0. Changelogs may suggest improvements applicable to the project. 1. Run go test ./... and go build ./... 2. Scan with govulncheck ./... or go tool govulncheck ./... 3. Release notes/changelogs for libraries that affect persistence, serialization, networking, authentication, authorization, cryptography, or public APIs may contain important information about breaking changes 4. Major version upgrades may contain breaking changes — the package's changelog documents them 5. New APIs or patterns introduced in the updated version may offer improvements worth considering

Dependency Conflicts & Resolution

Diagnosing Conflicts

# See why a module is in your build
go mod why -m github.com/some/module

# See which version is selected
go list -m github.com/some/module

# See the full requirement graph
go mod graph

# List all modules in the build
go list -m all

Resolution Strategies

Force a specific version (when two deps require incompatible versions):

go mod edit -replace=example.com/pkg@v1.2.0=example.com/pkg@v1.3.1

// go.mod
replace example.com/pkg v1.2.0 => example.com/pkg v1.3.1

Use a local fork (for debugging or patching):

replace example.com/pkg => ../my-local-fork

Block a problematic version:

go mod edit -exclude=example.com/pkg@v1.3.0

When a version is excluded, any requirement on that version is redirected to the next higher available version.

Force upgrade a transitive dependency:

go get github.com/transitive/dep@v1.5.0

This adds an explicit requirement in your go.mod, overriding whatever the transitive dependency chain would select via MVS.

Resolution Workflow

1. Run go mod graph and go mod why -m <module> to understand the dependency chain 2. Identify which of your direct dependencies pulls in the conflicting version 3. Try upgrading the direct dependency first: go get github.com/direct/dep@latest 4. If that doesn't resolve it, use replace or exclude as a temporary fix 5. Run go mod tidy to clean up 6. Verify with go build ./... and go test ./...

Important: replace and exclude directives only take effect in the main module's go.mod. They are ignored when your module is used as a dependency. Remove replace directives before publishing a library.

Retract (For Module Authors)

Mark versions as broken or accidentally published:

// go.mod
retract v1.0.0         // Contains critical bug in auth
retract [v1.1.0, v1.2.0] // Range of broken versions

Retracted versions are still downloadable but go get will not select them by default, and go list -m -u warns about them.

Versioning & Minimal Version Selection

Semantic Versioning (SemVer)

Go modules use `vMAJOR.MINOR.PATCH` (the v prefix is required):

• MAJOR: Breaking changes to the public API
• MINOR: Backward-compatible new functionality
• PATCH: Backward-compatible bug fixes

Stability Rules

Major Version Suffix Rule

For v2 and above, the module path must include a /vN suffix. This is Go's import compatibility rule — different major versions are treated as entirely separate modules, allowing them to coexist in the same build:

// go.mod
module github.com/example/pkg/v2

// Import in code
import "github.com/example/pkg/v2/subpkg"

Tags: v2.0.0, v2.1.0, etc. The v0 and v1 versions have no suffix.

Special Cases

• Pseudo-versions: For untagged commits — v0.0.0-20210101120000-abcdef123456 (base version + timestamp + commit hash)
• `+incompatible`: Marks v2+ modules that have not adopted the /vN path convention
• `gopkg.in`: Always uses a version suffix with a dot — gopkg.in/yaml.v3

Minimal Version Selection (MVS)

Go's dependency resolution algorithm is fundamentally different from npm, pip, or cargo.

How It Works

Most package managers select the latest compatible version of each dependency. Go does the opposite: it selects the minimum version that satisfies all requirements. If module A requires pkg@v1.2.0 and module B requires pkg@v1.3.0, MVS selects v1.3.0 — the highest minimum required, not the latest available.

Why This Design

• Deterministic without a lock file: Given the same go.mod inputs, MVS always produces the same build list. go.sum is just integrity verification.
• High fidelity: Builds closely match what module authors tested against, since the nearest compatible version is selected rather than the latest.
• No solver needed: The algorithm is simple graph traversal (under 50 lines of code), not an NP-hard constraint satisfaction problem.
• Reproducible across machines: No "works on my machine" from different lock file states.

Upgrades and Downgrades

• Upgrade: go get pkg@v1.5.0 adds an edge to v1.5.0 in the module graph and reruns MVS. Only the minimum necessary changes propagate.
• Downgrade: go get pkg@v1.2.0 removes all versions above v1.2.0 from the graph, then walks backward to find the latest remaining versions of affected dependencies.

Visualizing the Dependency Graph

go mod graph (Built-in)

go mod graph

Output: each line contains two space-separated fields (module and its requirement) in path@version format:

example.com/main github.com/google/uuid@v1.6.0
example.com/main golang.org/x/text@v0.3.7
github.com/google/uuid@v1.6.0 golang.org/x/sys@v0.0.0-20210615035016

go mod why

go mod why -m github.com/some/module

Shows the shortest import path from your code to the module — useful for understanding why an unexpected dependency exists.

Generate a Graph Image with modgraphviz

Pin modgraphviz as a module tool, then pipe go mod graph into it.

go get -tool golang.org/x/exp/cmd/modgraphviz@latest
go mod graph | go tool modgraphviz | dot -Tpng -o deps.png

Green nodes represent versions selected by MVS (in the final build list). Grey nodes are versions that exist in the requirement graph but are not used.

Interactive Visualization with go-mod-graph

go-mod-graph (samber/go-mod-graph) is a web-based interactive dependency explorer with zoomable graph, module weight indicators, searchable module list, and MVS algorithm visualization.

Complementary Analysis

Pin digraph as a module tool for graph queries.

go get -tool golang.org/x/tools/cmd/digraph@latest
# General graph queries on go mod graph output
go mod graph | go tool digraph reverse example.com/some/module

Go Workspaces (go.work)

go.work vs go.mod

Workspace Commands

go work init                    # Initialize workspace
go work use ./services/auth     # Add module to workspace
go work use -rm ./old-module    # Remove module from workspace
go work sync                    # Sync workspace with module changes

Key Points

• Workspaces eliminate the need for replace directives during local development — the workspace automatically resolves local modules
• Do not commit `go.work.sum` to version control (add to .gitignore)
• go.work is for development only — it does not affect how consumers of your published modules resolve dependencies
• For workspace directory structure examples, see the samber/cc-skills-golang@golang-project-layout skill