Modules and Dependency Management

Source: Go Modules Reference: Glossary

A commit that has no tag can still be required, by a pseudo-version that encodes a base, the UTC commit time and the first 12 characters of the commit hash. There are three forms, chosen so that a pseudo-version sorts after the version it is based on and before the next tagged release:

You rarely type one: go get example.com/lib@main (a branch) or go get example.com/lib@0123456789ab (a commit) resolves to one. The local proxy used on this page serves a snapshot module under an explicit pseudo-version:

Source: Go Modules Reference: Pseudo-versions

Pseudo-versions are for testing a fix before it is tagged. The go command checks that the commit really is on the history of the stated base tag, so a pseudo-version cannot be used to dodge MVS. Prefer a tagged release in anything you ship.

The import compatibility rule is the key idea: if an old and a new package have the same import path, the new one must be backwards compatible with the old one. A breaking change therefore needs a new import path, and modules get it by appending the major version to the module path:

The consequence is that two major versions of a module are two different modules and can be in one build, which lets a large program migrate gradually. The local proxy publishes both example.com/barcode v1.0.0 (with Encode(s string) string) and example.com/barcode/v2 v2.0.0 (with a changed signature, Encode(s string, width int) string). One file can import both:

Source: The Go Blog: Go Modules: v2 and Beyond

The go.mod after go mod tidy lists the two modules as unrelated requirements, and go list -m all shows both:

Source: Go Modules Reference: Major version suffixes

Two details. First, the major version suffix is /v2, never /v2.1; there is one module per major version, not per minor. Second, the module path is written in go.mod of the new major version (module example.com/barcode/v2), and a v2 release whose go.mod forgets the suffix is rejected. How to release a new major version is covered in Workspaces, Versioning and Publishing.

Some repositories tagged v2.0.0 or higher before they adopted modules and have no go.mod. The go command treats them as part of the v0/v1 module path and labels the version v4.1.2+incompatible. A +incompatible version is in the same module as v1, so go get -u may move up to it without warning that it may break the build. Libraries that adopt modules after tagging v2 should release a new major version with the /vN suffix rather than add a go.mod to the existing tags.

Source: Go Modules Reference: +incompatible versions

Anywhere a command accepts path@query, the query is resolved against the versions the proxy lists:

A throwaway module example.com/patchy with releases v1.0.0, v1.0.3, v1.1.0 and a pre-release v1.2.0-rc.1 shows the difference. Each line below follows the previous (the first adds v1.0.0):

Source: Go Modules Reference: Version queries

Notice that @latest downgraded from the pre-release: latest means the newest release, and an explicit pre-release is not one. Quote queries containing < or > so the shell does not treat them as redirections, and note that only a single comparison is accepted (a range such as >=1.0.3,<1.1.0 is rejected with invalid semantic version).

The go line states the language version the module is written in and, since Go 1.21, is a strict minimum: a toolchain older than the line refuses to build the module, and it must be greater than or equal to the go line of every dependency. Its effects:

Source: Go Modules Reference: go directive

Source: Go 1.27 release notes: go test

A go line can be raised by go get go@1.27.2 (or go get go@latest, which needs the network and was not run here) and by go mod tidy -go=1.27. Raising it below what a dependency needs is not possible: go mod tidy bumps a go 1.16 line to go 1.21 when a dependency declares go 1.21.

When a go.mod asks for more than the installed go command, Go 1.21 and later switch toolchains rather than fail. GOTOOLCHAIN (default auto) controls this: local never switches, go1.27.2 pins a release, and go1.27.2+auto means "at least this, switch if go.mod says more". The main module’s toolchain line (for example toolchain go1.27.2) suggests a toolchain at least as new as the go line; it matters only when it is newer than the toolchain that would otherwise be used. With the module requiring Go 1.28 on a machine whose toolchain is 1.27.2:

Source: Go Toolchains

With GOTOOLCHAIN=auto the second command would download golang.org/toolchain@v0.0.1-go1.28.0.<os>-<arch> from the module proxy and run it (an unreleased 1.28.0 is not available, hence the real error above; the download itself is not run here). The downloaded toolchain is itself a module, verified against the checksum database like any other. Since Go 1.25 the go command no longer adds a toolchain line when it updates the go line, so the line is mostly something you write on purpose. go get go@1.27.2 also drops a redundant toolchain go1.27.2:

Source: Go Toolchains: go get and the toolchain line

GODEBUG=toolchaintrace=1 (Go 1.24) prints the toolchain-selection steps; the full story, including how a dependency that needs a newer Go than yours is handled, is in Toolchain Versions and Compatibility.

Go keeps old behaviour behind GODEBUG settings so that a go 1.2x module keeps working when it builds with a newer toolchain. The go line chooses the defaults; the godebug directive overrides single settings for the whole main module, as if every main package had //go:debug key=value. panic(nil) showed in Go 1.21 how this works: the program recovers a *runtime.PanicNilError, unless panicnil=1 restores the old behaviour.

Source: Go, Backwards Compatibility, and GODEBUG

The same setting can be placed in the source of the main package, which is recorded in the binary and visible with go version -m (the DefaultGODEBUG build setting):

Source: Go, Backwards Compatibility, and GODEBUG: How is GODEBUG used?

godebug default=go1.21 sets the whole behaviour baseline to an older release. Three rules protect you from typos and from stale settings. A key that does not exist is an error in the main module; and, new in Go 1.27, a setting whose support was removed (like asynctimerchan, whose last behaviour is now unconditional) is accepted only with its final value:

Source: Go 1.27 release notes: GODEBUG

require path version states the minimum version of a module the main module needs; the version actually used is the one MVS selects (next section). The // indirect comment marks a requirement that no package of the main module imports. Since Go 1.17 these indirect lines are there on purpose, so the go command can read only the main go.mod to find every module that contributes code. Run go mod tidy to get the comments right. Right after go get they may be wrong, which is a real example of why tidy exists:

Source: Go Modules Reference: require directive

The program being built is the one from the running scenario’s command:

Source: Go Modules Reference: go mod tidy

The last two lines show something to remember: isbn v1.2.0 asks for checksum v1.3.0, textutil v1.1.0 asks for v1.4.0, and the program is built with v1.4.0, the highest of the requested minimums.

A comment paragraph that begins with Deprecated: immediately before the module line marks the whole module as deprecated (the text after the colon is the message). The go command prints it when the module is added, and go list -m -u marks it:

Source: Go Modules Reference: Module deprecation

The deprecation notice is read from the latest version of the module, so a module can be deprecated after the fact by publishing one more release. Individual packages are deprecated with a Deprecated: paragraph in their package comment (see Documentation and Doc Comments).

retract is for the author of a module: it says that some versions were published by mistake or contain a severe problem. The go command then never upgrades to them automatically and warns anyone who requires them. The directive takes a single version or a closed range [v1.0.0, v1.0.5], with a rationale in a comment:

Retractions are read from the highest version of the module (the one @latest resolves to before retractions are applied), so to retract you publish a new release containing the directive. A retracted version stays available, so existing builds do not break. Users learn about it when they check for updates or ask for it explicitly:

Source: Go Modules Reference: retract directive

Retraction is a communication mechanism, not a security boundary: it relies on consumers running go list -m -u, go get or a tool such as govulncheck. A vulnerability is reported separately, through the Go vulnerability database (see Crypto and Security).

exclude path version stops the go command from ever using a version, in the main module only. It is the blunt tool for "this version is broken for me, and I cannot change who requires it". MVS skips the excluded version and selects the next higher one that is not excluded:

Source: Go Modules Reference: exclude directive

Prefer a retract (if you own the module) or a normal require of a fixed version over exclude. The directive has no effect in modules you depend on, so it cannot protect your consumers.

replace substitutes the contents of a module. The left side is a module path with an optional version (without a version, all versions are replaced); the right side is either another module path with a version, or a local directory. Replacements apply only in the main module, which makes them right for forks and local development and wrong for anything your own consumers must see.

=> points example.com/textutil at a local fork next to the project:

Source: Go Modules Reference: replace directive

The local directory must contain a go.mod with the replaced module’s path. Local replacements need no go.sum entries (no download, nothing to verify), and the replaced v1.1.0 is still the version recorded in go.mod, since that is what other modules in the graph refer to. A replacement with a version is the way to pin a module to a different release without touching what dependencies request:

If you forget the go mod tidy after adding a versioned replacement, the next build reports the missing hashes (missing go.sum entry for module providing package ...), because the replacement version needs its own go.sum line. A replace that points to a local path must never be published: other modules cannot see your directory, which is why go mod edit -replace is for development and workspaces (Workspaces, Versioning and Publishing) are the better tool for multi-module work.

Programs that a project needs while developing (a code generator, a linter, stringer) used to be pinned by a blank import in a file named tools.go guarded by //go:build tools, so that go mod tidy kept their module in go.mod. Go 1.24 made this a first-class feature: a tool directive names a main package of a dependency, and go tool runs it.

The local proxy publishes example.com/lintkit, whose cmd/shelflint is a main package:

Source: Managing dependencies: Tools

Everything works through the same machinery as ordinary dependencies, so tool versions are pinned by go.mod and verified by go.sum:

The tools.go file is now unnecessary (and its //go:build tools constraint is just a way to keep a file out of every build). Delete it, run go get -tool for each import, then go mod tidy. When a tool is installed for use outside any project, go install with an explicit version ignores go.mod altogether:

Source: Go Modules Reference: go install

(The output of go version -m continues with the build settings such as GOOS, GOARCH and CGO_ENABLED.) go install pkg@version and go install pkg@latest are how end users install a command; go get never builds programs any more. See The go Command, Builds and Cross-Compilation for go version -m and build metadata, and Packaging & Distribution for how command-line programs are distributed (including go install as a channel).

Since Go 1.25 an ignore directive tells package patterns (./..., all, work) to skip directories. A directory that starts with ./ is relative to the module root; any other path matches a directory with that name at any depth. A web front end whose node_modules contains stray .go files, or a documentation folder with snippets that do not compile, no longer break go vet ./...:

Source: Go Modules Reference: ignore directive

The ignored files are still part of the module (they are included in the module zip file) and an explicit import or an explicit directory argument still works, as the last command shows. Directories whose name starts with . or _, or is testdata, were already skipped by ./...; ignore is for the others.

go mod edit changes go.mod without resolving anything, so it never touches the network and does not change go.sum. Its flags map one-to-one onto the directives:

Source: Go Modules Reference: go mod edit

(The listing is abridged where it ends in ....) The JSON form is what scripts should read; golang.org/x/mod/modfile is the library behind it, for programs that need to parse or rewrite go.mod themselves.

MVS makes upgrading local and downgrading expensive, and the go get output says so. Raising the shared dependency is a one-line change; lowering it below what a module needs removes that module, since a lower checksum can no longer satisfy textutil:

Source: Go Modules Reference: Downgrading a module

The go.mod is the artifact to review after any of these commands. A dependency added by accident is as likely to appear in a pull request as a changed line of code. The four things that can change what MVS selects are exactly the ones that edit go.mod: require (a higher minimum), exclude (a version removed from the candidate set), replace (a version’s contents changed) and go get (any of them, automatically).

Taken literally, the graph of a large project is huge: every transitive requirement of every module, back to the start of time. Go 1.17 introduced two optimizations that apply when the main module says go 1.17 or later:

A pruned module is still in go list -m all (its version is known), but the modules it requires are not looked at unless something else needs them. The effect is visible with a module example.com/report that requires example.com/pdfkit, which requires example.com/fontkit and example.com/checksum v1.5.0, none of which report imports. Release v1.0.0 declares go 1.21 and release v0.9.0 declares go 1.16, which predates pruning:

Source: Go Modules Reference: Module graph pruning

With the go 1.21 release (the first graph) the requirements of pdfkit are not loaded: fontkit and checksum do not even appear in go list -m all. With the go 1.16 release (the second) the whole transitive closure is loaded, and checksum v1.5.0, which nothing the program imports needs, takes part in version selection. The practical consequence is faster go commands and smaller go.sum files in large dependency trees, and one thing to know: because go.mod lists indirect requirements explicitly at go 1.17 or later, go mod tidy can make go.mod longer, and that is by design.

Source: Go Modules Reference: Lazy module loading

go get adjusts the requirements in go.mod (and downloads what it needs). It no longer builds or installs anything. Its synopsis is go get [-t] [-u] [-tool] [build flags] [packages], and each argument is a package or module path with an optional @query:

Source: cmd/go: Add dependencies to current module and install them

Things worth knowing:

Source: Go Modules Reference: go get

go mod tidy makes go.mod and go.sum match the source: it adds requirements for every imported package that has none, removes requirements that no package needs, adds the missing hashes and prunes the unused ones. It is what you run after adding or removing an import, before committing, and in CI.

Source: Go Modules Reference: go mod tidy

Flags:

Tidy looks at every build constraint combination (all operating systems and architectures), including test files of the main module’s packages, but only the tests of packages it must load itself for dependencies of the main module.

go list -m reports modules rather than packages. The few forms you will use daily:

Source: Go Modules Reference: go list -m

-u shows available upgrades in brackets (and (deprecated) or (retracted)), -versions lists the known versions, -retracted includes retracted ones, and -json prints the Module struct: path, version, time, Indirect, the local Dir and GoMod paths, GoVersion, the Sum and GoModSum hashes, and Replace when replaced:

Source: cmd/go: List packages or modules

go list -deps with a template maps packages back to modules, which is a quick answer to "which module does this binary link":

(Run on the program that includes the labels.go file from the major-version section.) Since Go 1.25 the work package pattern matches all packages of the main module, or all modules of a workspace; all also includes the dependencies and the standard library:

Source: Go 1.25 release notes: Go command

go mod why answers "why is this here?" with the shortest import path from the main module. With -m it works on modules. (main module does not need ...) tells you the requirement is unused (and go mod tidy will remove it):

Source: Go Modules Reference: go mod why

By default why considers tests of reachable packages; -vendor excludes tests of dependencies. go mod graph (shown above) is the machine-readable graph; its -go=version flag prints the graph as another Go version would load it (a version too old for the module is refused: requested Go version 1.16 cannot load module graph (requires Go >= 1.27)).

go mod download fills the module cache without building. With no argument it downloads the modules needed by the main module; with path@version queries it downloads those, and -json prints one record per module, including the paths of the cached .info, .mod, .zip and extracted directory and the hashes that belong in go.sum:

Source: Go Modules Reference: go mod download

The go command downloads modules on demand during ordinary builds, so go mod download is mainly for priming a cache in a Docker layer or CI cache, and for computing the answers a proxy has to serve. -reuse=old.json lets a repeated invocation skip unchanged modules, and -x prints the commands that run.

The module cache has two parts. cache/download is the raw downloads (what a proxy serves, plus a ziphash and a lock file); the extracted source trees sit directly under $GOMODCACHE, named path@version, with every file read-only so that an accidental edit does not corrupt every project on the machine:

Source: Go Modules Reference: Module cache

Management of the cache:

go mod verify re-hashes the extracted source trees in the cache and compares them with the hashes recorded when they were downloaded, to detect local tampering or corruption:

Source: Go Modules Reference: go mod verify

(The tampered file needed chmod u+w first, since extracted files are read-only. Deleting the directory is the fix: the go command re-extracts it from the verified zip.) Note that an ordinary go build does not re-hash the extracted tree: a build between the second and third commands succeeds with the modified source. go mod verify is the check to run in CI or before building releases on shared machines.

If the downloaded bytes disagree with go.sum, the go command stops and deletes the download. Changing one character of the isbn hash in go.sum, with an empty cache:

Source: cmd/go: Module authentication using go.sum

The cause may be an innocent one (a force-pushed tag on a repository served directly, a hand-merged go.sum), but the message is deliberately loud. Never "fix" it by deleting go.sum lines without finding out why. The opposite problem, a missing line, is a different, harmless error, fixed with go mod tidy or the go get the message names:

By default the build uses -mod=readonly: go build and go test refuse to edit go.mod or go.sum. Only go get, go mod tidy and a few other explicit commands do, so a build can never quietly change what you depend on.

A go.sum protects against a module changing after you first saw it, but who vouches for the first sight? The checksum database (sum.golang.org) is a global, append-only transparency log (a Merkle tree) of the hash of every public module version. When a hash is not in go.sum, the go command asks the log, verifies a signed tree head and an inclusion proof, and only then trusts the download and writes the line. This makes an untrusted proxy possible: it can serve bytes quickly, but it cannot serve different bytes to you than to anyone else without the log noticing.

(GOSUMDB and GOPROXY defaults from a clean environment; the other two are empty by default. Contacting the log was not run on this page: it needs the network, and the demonstration modules are not in it.)

Source: Go Modules Reference: Checksum database

The design and the rest of the supply-chain properties of Go modules (no install scripts run on download, versions never change, the version control system is the source of truth) are described in the announcement of the mirror and in the supply-chain post: The Go Blog: Module Mirror and Checksum Database Launched, The Go Blog: How Go Mitigates Supply Chain Attacks.

GOPROXY is a comma- or pipe-separated list of proxy URLs, plus two keywords: direct (fetch from the version control system or the origin server named by the module path) and off (never fetch, fail). The default is https://proxy.golang.org,direct. The separator controls fallback: after a comma the next entry is tried only if the previous one answered 404 or 410 (the module is not there); after a pipe it is tried after any error. A company proxy that must never be bypassed is GOPROXY=https://proxy.example.com (no direct), and one that falls back only on "not found" is https://proxy.example.com,direct.

The module proxy at proxy.golang.org is a cache and mirror run by Google: it serves modules fast, keeps them available when the original repository disappears, and is the reason a deleted tag does not break builds. The same protocol is what private Artifactory, Nexus, Athens or GitHub-package style proxies implement, and a local directory works too, because every request is a plain GET with no query and no special headers.

Source: cmd/go: Module proxy protocol

The protocol has five requests (module paths are case-encoded: ! plus the lower-case letter for every upper-case letter):

Source: Go Modules Reference: GOPROXY protocol

This is the whole of the local proxy used on this page, a directory tree served as GOPROXY=file://...:

Source: Go Modules Reference: Serving modules directly from a proxy

With GOPROXY=off, only what is already in the cache can be used:

Source: Go Modules Reference: Environment variables

That is the setting for air-gapped builds, together with go mod download on a connected machine to fill the cache (or a vendor directory, below), and a Docker build that copies go.mod and go.sum first so the download layer is cached.

When an import is not provided by any module in the build list, the go command asks the proxy for the latest version of every module path that could contain it (for example.com/a/b/c: the modules example.com/a/b/c, example.com/a/b, example.com/a and example.com), takes the longest path that exists and records its latest version in go.mod. A package that resolves to two modules (an ambiguous import) is an error you fix by requiring a version that no longer contains the package.

Source: Go Modules Reference: Resolving a package to a module

With direct, or when a path matches GONOPROXY, the go command fetches from the source repository. It first asks the server for the go-import metadata (<meta name="go-import" content="root-path vcs repo-url">, which a vanity domain serves with a redirect to the real host), then runs the version control tool. Since Go 1.25 a go-import tag can carry a fourth field, a subdirectory of the repository, so the module root need not be the repository root. Support for bzr was removed in Go 1.27, so bzr servers are no longer fetched directly.

For safety, the go command only uses git and hg against public servers by default, and any known system (git, hg, svn, fossil) for private ones. GOVCS changes that with pattern:vcslist rules; the first matching rule wins, public and private are keywords, off forbids a tool and all allows everything:

Source: cmd/go: Controlling version control with GOVCS

(These are two alternatives, shown as a setting; the examples were not executed because they act on repositories.) When a module is downloaded through a proxy, none of this applies: the proxy protocol is always allowed, which is why proxy.golang.org is the default and the safer path for public code.

Private servers need credentials, and the old choices were a .netrc file (machine ... login ... password ...), a Git credential helper or an HTTP proxy that adds the header. Go 1.24 added GOAUTH, a semicolon-separated list of authentication commands the go command runs before it fetches over HTTPS:

A sketch with placeholders (not run: it needs a real private server and valid credentials):

Source: cmd/go: GOAUTH environment variable

Store real tokens in a secret manager and a credential helper, never in a committed .netrc or in the Dockerfile; the examples above contain only placeholders. A token that appears in go.mod, go.sum or a build log has been leaked. Setting GOFLAGS=-mod=mod or enabling GOINSECURE for a host never replaces authentication.

The defaults come from a clean go env (home directory /home/me); a configured environment file or the process environment overrides them.

Source: Go Modules Reference: Environment variables

go mod vendor copies the packages needed to build and test the main module into a vendor directory, plus a manifest vendor/modules.txt that records the module versions. It is how you freeze a build inside the repository:

Source: Go Modules Reference: go mod vendor

The build succeeded with GOFLAGS empty because, for a module at go 1.14 or later, a present and consistent vendor directory is used automatically (equal to -mod=vendor). Only packages are copied (not go.mod or go.sum files, not test files of dependencies); modules that contribute no package are absent; and go mod vendor ignores build constraints so that the copy works on every platform. -v prints the list, -e continues past errors and -o dir writes somewhere else (for other tools, since the go command only reads vendor at the module root).

The manifest is checked against go.mod. If the two drift apart, the build stops instead of using stale source:

Source: Go Modules Reference: Vendoring

-mod is the build flag that decides how go.mod is treated, and GOFLAGS=-mod=... sets it for a shell:

Source: cmd/go: Compile packages and dependencies (build flags -mod, -modfile and -modcacherw)

-modfile=other.mod makes the command use an alternative go.mod (with a matching other.sum), which is handy for build experiments that must not touch the committed files.

Vendoring trades repository size and review noise for build independence. Many teams do not vendor, relying on the proxy cache and on go.sum, and vendor only for air-gapped builds or when license or audit rules require every dependency to be in the tree. Direct pull requests to a vendored dependency’s files are not a good way to change it; use a fork and replace.