Mastering Go Modules: Version Suffixes, Path Resolution, and go.mod Essentials

4. Major Version Suffix

From major version 2 onward, the module path must include a suffix that matches the major version, for example example.com/test/v2. The suffix enforces import compatibility: a new major version is not backward compatible with the previous one, so a different import path is required.

Modules with a new major version provide packages that are not backward compatible; adding the suffix to the module path gives each incompatible version a distinct import path.

Major versions v0 and v1 do not use a suffix because v0 is unstable and v1 is expected to be backward compatible with the latest v0.

Modules prefixed with gopkg.in always require a major version suffix, even for v0/v1, and the suffix starts with a dot (e.g., gopkg.in/yaml.v2).

The suffix allows multiple major versions to coexist, solving diamond dependency conflicts. When two different versions of a module are required, the one with the longest matching path wins.

Modules that were released before Go Modules and already have a v2+ tag but no suffix are marked with +incompatible (e.g., v2.0.0+incompatible).

5. Resolving Package Path to Module Path

When go get is given a package path, the Go command searches the build list of the main module for a module whose path is a prefix of the package path. If a matching module is found and the directory contains at least one Go source file, that module is used; otherwise an error is reported. The -mod=mod flag forces the command to download missing modules and update go.mod and go.sum. go get and go mod tidy perform these steps automatically.

The command consults the GOPROXY environment variable, a comma‑separated list of proxy URLs plus the keywords direct and off. It queries each proxy for the module path prefixes, selects the longest matching path, and downloads the latest version. If a proxy returns 410/404, the next proxy in the list is tried, finally falling back to https://proxy.golang.org. When a module is found, its path and version are added to the main module’s go.mod; indirect dependencies are marked with // indirect.

6. The go.mod File

The module is defined by a UTF‑8 go.mod file consisting of line‑oriented directives such as module, go, require, exclude, replace, and retract. Example:

module example.com/my/thing
go 1.17
require example.com/other/thing v1.0.2
require example.com/new/thing/v2 v2.3.4
exclude example.com/old/thing v1.2.3
replace example.com/bad/thing v1.4.5 => example.com/good/thing v1.4.5
retract [v1.9.0, v1.9.5]

Directives can be grouped, e.g.:

require (
    example.com/new/thing/v2 v2.3.4
    example.com/old/thing v1.2.3
)

The golang.org/x/mod/modfile package can manipulate go.mod programmatically. Its File struct includes fields such as Module, Go, Require, Exclude, Replace, and Retract. The Deprecated field, added later, allows a module author to warn users that a version is no longer maintained and point them to a newer major version, e.g.:

// Deprecated: in example.com/a/[email protected], the latest supported version is example.com/a/b/v2.
module example.com/a/b
go 1.17

When a user runs go get -d example.com/a/[email protected], the tool prints a warning that the module is deprecated and suggests the v2 path.