go.mod: Root of Go Module Identity

WHY IT EXISTS: Go manages dependencies through modules. The module system treats a directory of related packages as a single unit that is released, versioned, and distributed together. A go.mod file in the module root declares the module's canonical path and dependency information so the go command can fetch the correct code from version control repositories or module proxy servers.

THE MENTAL MODEL: Think of go.mod as the deed to a plot of land. It states the address where the property is located, and it records who the neighbors are. The address is the module path, which must be unique and tell the world exactly where to find your code. Without this deed, the Go toolchain cannot locate your module among the thousands of packages stored in version control repositories and proxy servers.

HOW IT WORKS: A module is a collection of packages that are released, versioned, and distributed together. The go.mod file lives in the module root directory and declares the module path, which serves as the canonical name and the prefix for every package path inside the module. For example, if the module path is golang.org/x/net, then the package in the html subdirectory has the package path golang.org/x/net/html. The go command downloads modules directly from version control repositories or from module proxy servers. The module path itself encodes the repository root path, and if the module is not at the repository root, it includes the subdirectory name. For major versions 2 and higher, the module path must end with a major version suffix such as /v2 so the go command can resolve the correct version.

WHEN TO USE IT: You need a go.mod file at the root of every Go project that uses modules. It is required the moment you want to import an external package or allow another module to import yours. The module path you choose should describe both what the module does and where to find it, typically matching the repository root path.

WHEN NOT TO USE IT: You should avoid inventing module paths that collide with the Go standard library or your dependencies. You must also never release major version 2 or higher without appending the required /v2 suffix to the module path, because the go command relies on that suffix to locate and download the correct module version. There are also lexical restrictions on characters allowed in module paths, so paths must be chosen carefully.

ONE CANONICAL EXAMPLE: The module golang.org/x/tools/gopls resides in the gopls subdirectory of the repository whose root path is golang.org/x/tools. Its module path is therefore golang.org/x/tools/gopls. If the team behind it released a v2, the module path would need to become golang.org/x/tools/gopls/v2, and the code would need to live in a directory matching that path so the go command could fetch it correctly.