Go Modules & Dependency Management Guide

Go Modules System

Go modules, introduced in Go 1.11 and made the default in Go 1.16, replaced GOPATH and vendoring as the official dependency management system. A module is a collection of Go packages with a shared versioning strategy, defined by a go.mod file at the module root. The go.mod file declares the module path, the Go version required, and dependency requirements with their versions. The go.sum file contains cryptographic checksums of each dependency module, ensuring reproducible and tamper-proof builds. The Go module system integrates with the centralized Go module mirror (proxy.golang.org) for fast, reliable dependency downloads and with the checksum database (sum.golang.org) for security verification. Russ Cox’s series of articles on “Go & Versioning” (research.swtch.com/vgo) provides the design rationale behind the module system. The module system eliminated the long-standing GOPATH pain points, making dependency management a first-class, built-in feature of the Go toolchain. The transition to modules was one of the most significant infrastructure changes in Go’s history, requiring updates to nearly every Go project and tool.

Module Initialization and Structure

Creating a new module:

go mod init github.com/user/project

This generates go.mod:

module github.com/user/project

go 1.22

The module path serves as the root import path for all packages within the module. The Go version directive sets the minimum Go version required to build the module and controls which language features are available. For projects with multiple subdirectories, each subdirectory becomes a separate package within the same module, all sharing the same versioning strategy. Monorepos can use multiple modules at different subdirectory levels, though single-module monorepos are more common. The module path should match the repository location to enable go get to find the module.

Adding and Managing Dependencies

Dependencies are declared in go.mod when code imports external packages. Running go mod tidy syncs the module’s dependencies:

go mod tidy

This command adds any missing modules needed by imports in the codebase, removes modules no longer imported, and updates go.sum with checksums for all direct and indirect dependencies. The go.sum file includes entries for all modules in the dependency graph, including transitive dependencies. Use go mod verify to check that cached dependencies match go.sum. For understanding the dependency graph, go mod graph prints all module dependencies in a format suitable for visualization. The go mod why command explains why a specific dependency is required, which is invaluable for debugging unexpected dependency additions.

Semantic Versioning in Go Modules

Go modules follow semantic versioning (semver): vMAJOR.MINOR.PATCH. Major version zero (v0.x.x) indicates unstable development with no compatibility guarantees. For major versions v2+, the module path includes the version suffix:

import (
    "github.com/user/pkg"
    "github.com/user/pkg/v2"
)

This allows multiple major versions of the same package to coexist in a single build. The +incompatible annotation marks packages at v2+ without module path versioning, used for legacy compatibility. Go modules use “minimal version selection” (MVS) to resolve dependency conflicts: when two dependencies require different versions of the same module, the highest required version wins. MVS is deterministic and produces the same result on all machines. Pseudo-versions like v0.0.0-20250101120000-abcdef123456 allow pinning to specific commits in the absence of tagged releases.

Private Module Configuration

Private repositories require explicit bypassing of the public Go proxy:

go env -w GOPRIVATE=github.com/company/*
go env -w GONOSUMDB=github.com/company/*
go env -w GONOPROXY=github.com/company/*

GOPRIVATE tells the Go toolchain not to use the proxy or checksum database for matching modules. GONOSUMDB and GONOPROXY provide finer-grained control. Git authentication uses ~/.netrc or the GIT_TERMINAL_PROMPT environment variable for private repository access. For enterprise environments, running a local Go module proxy (e.g., Athens or Artifactory) provides caching, access control, and audit capabilities for internal dependencies.

Vendoring

The vendor/ directory copies dependency source code into the module tree, enabling reproducible builds without network access:

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

Vendoring is standard in enterprise environments with air-gapped build systems. Module graph pruning (Go 1.17+) removes unused dependencies from go.mod. The go mod vendor command generates a vendor/modules.txt manifest that records which modules and packages were vendored.

Workspaces (Go 1.18+)

Go workspaces enable working on multiple interdependent modules simultaneously:

go work init ./module-a ./module-b

The go.work file overrides the require directives in individual module files, directing the compiler to use local source code instead of published versions. Workspaces are a development-only feature.

Dependency Management Best Practices

Production Go projects should follow established dependency management practices. Pin direct dependencies explicitly in go.mod and avoid wildcard version ranges. Run go mod tidy -go=1.22 to set the Go version directive appropriately. Use go mod verify in CI to ensure dependency integrity. For multi-repository projects, consider replacing go get with go mod download in Docker builds for layer caching efficiency. The GONOSUMCHECK environment variable allows excluding specific modules from checksum database verification, useful for internal packages. Regularly audit dependencies using nancy or govulncheck for known vulnerabilities. The go mod why -m command traces why a specific module is required, helping identify unnecessary transitive dependencies. For monorepos, evaluate whether a single module or multiple modules better serve the project: single modules simplify refactoring but increase build scope for CI. The golang.org/x/exp repository hosts experimental module features that may enter the standard library in future releases.

Advanced Module Operations

Beyond basic dependency management, Go modules support advanced workflows. The go mod replace directive substitutes a module with a local path or alternative version, essential for debugging dependencies: replace example.com/old v1.2.3 => ./local/fork. The go mod vendor command combined with -mod=vendor flag creates reproducible offline builds. Module graph pruning in Go 1.17+ removes unused transitive dependencies from go.sum, reducing file size. The GOWORK environment variable enables workspace-mode builds without a go.work file, useful in CI environments. The go mod download -json flag outputs module information as JSON for tooling integration. For private module authentication, the GOPRIVATE environment variable combined with ~/.netrc or GIT_ASKPASS handles credentials. Multi-module monorepos benefit from the go.work file’s use directive for local development while CI builds use individual module directories. The go mod tidy -diff flag (Go 1.21+) shows changes without applying them, useful for validation in CI. Module deprecation is indicated by go mod edit -deprecated="use v2 instead", which displays deprecation messages to downstream consumers.

Semantic Import Versioning

Go modules enforce semantic import versioning (SIV) for major version bumps. When a module reaches v2+, the import path includes the major version: example.com/module/v2. The go.mod file lists example.com/module/v2 v2.0.0, and source imports use import "example.com/module/v2/pkg". This allows v1 and v2 to coexist in the same binary, unlike most package managers. The go mod tidy command handles retracting invalid versions with go mod edit -retract=v1.5.0. A retracted version is still downloadable but go mod tidy prefers the next highest non-retracted version. The go.mod retract directive supports both single versions and ranges: retract (v1.0.0, v1.5.0).

Pre-release versions follow the semver convention: v1.0.0-beta.1, v1.0.0-rc.1. Go’s module proxy (proxy.golang.org) caches module versions and enforces immutability — a published version cannot be modified. For private modules, the GONOSUMCHECK environment variable bypasses the checksum database, and GONOPROXY bypasses the module proxy. The go mod verify command checks that cached modules match the go.sum hash. CI pipelines should run go mod verify to detect tampering. The go mod download command pre-populates the module cache, ensuring reproducible builds without network access during compilation.

Workspace Mode for Multi-Module Repositories

Go 1.18+ workspace mode (go.work) coordinates development across multiple modules without editing each go.mod file. The go work init command creates a go.work file. The go work use ./module-a ./module-b directive adds local modules. The go work use -r . scans recursively. Workspaces replace individual replace directives during development, and the go.work file should not be committed to CI — individual module references remain in go.mod.

The GOWORK environment variable selects a workspace file; empty means no workspace. The go work sync command synchronizes dependency versions across workspace modules. Workspace mode supports vendor directories with go mod vendor -workspace. The go.work.sum file tracks checksums for workspace-level dependencies. For multi-module CI testing, the go test ./... command tests all workspace modules. The go build ./... builds all packages across workspace modules. Pre-commit hooks should run go work use to add new modules automatically. For large monorepos, workspace mode replaces the previous gopls multi-module configuration and simplifies editor integration.

Frequently Asked Questions

What is the difference between go get and go mod tidy? go get updates a specific dependency to a specified version. go mod tidy reconciles the entire dependency graph.

How do I update all dependencies to their latest versions? Use go get -u ./... to update all direct and indirect dependencies to their latest minor or patch versions.

What is the Go module proxy? The Go module proxy (proxy.golang.org) caches module versions for faster downloads and reliable builds.

How do I handle breaking changes in v2+ modules? Create a v2/ subdirectory in the module root with a go.mod whose module path includes the /v2 suffix.

What happens when two dependencies require different versions of the same module? Go modules perform minimal version selection: the highest required version wins.

Related: Go Generics Guide | Go JSON Serialization | Go Testing Frameworks