Modules are how Go manages dependencies.
This document is a detailed reference manual for Go's module system. For an introduction to creating Go projects, see How to Write Go Code. For information on using modules, migrating projects to modules, and other topics, see the blog series starting with Using Go Modules.
A module is a collection of packages that are released, versioned, and distributed together. Modules may be downloaded directly from version control repositories or from module proxy servers.
A module is identified by a module path, which is declared in a go.mod
file, together with information about the module's dependencies. The module root directory is the directory that contains the go.mod
file. The main module is the module containing the directory where the go
command is invoked.
Each package within a module is a collection of source files in the same directory that are compiled together. A package path is the module path joined with the subdirectory containing the package (relative to the module root). For example, the module "golang.org/x/net"
contains a package in the directory "html"
. That package's path is "golang.org/x/net/html"
.
A module path is the canonical name for a module, declared with the module
directive in the module‘s go.mod
file. A module’s path is the prefix for package paths within the module.
A module path should describe both what the module does and where to find it. Typically, a module path consists of a repository root path, a directory within the repository (usually empty), and a major version suffix (only for major version 2 or higher).
golang.org/x/net
is the repository root path for the module of the same name. See Finding a repository for a module path for information on how the go
command locates a repository using HTTP requests derived from a module path.golang.org/x/tools/gopls
is in the gopls
subdirectory of the repository with root path golang.org/x/tools
, so it has the module subdirectory gopls
. See Mapping versions to commits and Module directories within a repository./v2
. This may or may not be part of the subdirectory name. For example, the module with path golang.org/x/repo/sub/v2
could be in the /sub
or /sub/v2
subdirectory of the repository golang.org/x/repo
.If a module might be depended on by other modules, these rules must be followed so that the go
command can find and download the module. There are also several lexical restrictions on characters allowed in module paths.
A version identifies an immutable snapshot of a module, which may be either a release or a pre-release. Each version starts with the letter v
, followed by a semantic version. See Semantic Versioning 2.0.0 for details on how versions are formatted, interpreted, and compared.
To summarize, a semantic version consists of three non-negative integers (the major, minor, and patch versions, from left to right) separated by dots. The patch version may be followed by an optional pre-release string starting with a hyphen. The pre-release string or patch version may be followed by a build metadata string starting with a plus. For example, v0.0.0
, v1.12.134
, v8.0.5-pre
, and v2.0.9+meta
are valid versions.
Each part of a version indicates whether the version is stable and whether it is compatible with previous versions.
v1.2.3-pre
comes before v1.2.3
.go.mod
files. The suffix +incompatible
denotes a version released before migrating to modules version major version 2 or later (see Compatibility with non-module repositories.A version is considered unstable if its major version is 0 or it has a pre-release suffix. Unstable versions are not subject to compatibility requirements. For example, v0.2.0
may not be compatible with v0.1.0
, and v1.5.0-beta
may not be compatible with v1.5.0
.
Go may access modules in version control systems using tags, branches, or revisions that don‘t follow these conventions. However, within the main module, the go
command will automatically convert revision names that don’t follow this standard into canonical versions. The go
command will also remove build metadata suffixes (except for +incompatible
) as part of this process. This may result in a pseudo-version, a pre-release version that encodes a revision identifier (such as a Git commit hash) and a timestamp from a version control system. For example, the command go get -d golang.org/x/net@daa7c041
will convert the commit hash daa7c041
into the pseudo-version v0.0.0-20191109021931-daa7c04131f5
. Canonical versions are required outside the main module, and the go
command will report an error if a non-canonical version like master
appears in a go.mod
file.
A pseudo-version is a specially formatted pre-release version that encodes information about a specific revision in a version control repository. For example, v0.0.0-20191109021931-daa7c04131f5
is a pseudo-version.
Pseudo-versions may refer to revisions for which no semantic version tags are available. They may be used to test commits before creating version tags, for example, on a development branch.
Each pseudo-version has three parts:
vX.0.0
or vX.Y.Z-0
), which is either derived from a semantic version tag that precedes the revision or vX.0.0
if there is no such tag.yymmddhhmmss
), which is the UTC time the revision was created. In Git, this is the commit time, not the author time.abcdefabcdef
), which is a 12-character prefix of the commit hash, or in Subversion, a zero-padded revision number.Each pseudo-version may be in one of three forms, depending on the base version. These forms ensure that a pseudo-version compares higher than its base version, but lower than the next tagged version.
vX.0.0-yyyymmddhhmmss-abcdefabcdef
is used when there is no known base version. As with all versions, the major version X
must match the module's major version suffix.vX.Y.Z-pre.0.yyyymmddhhmmss-abcdefabcdef
is used when the base version is a pre-release version like vX.Y.Z-pre
.vX.Y.(Z+1)-0.yyyymmddhhmmss-abcdefabcdef
is used when the base version is a release version like vX.Y.Z
. For example, if the base version is v1.2.3
, a pseudo-version might be v1.2.4-0.20191109021931-daa7c04131f5
.More than one pseudo-version may refer to the same commit by using different base versions. This happens naturally when a lower version is tagged after a pseudo-version is written.
These forms give pseudo-versions two useful properties:
The go
command performs several checks to ensure that module authors have control over how pseudo-versions are compared with other versions and that pseudo-versions refer to revisions that are actually part of a module's commit history.
v1.999.999-99999999999999-daa7c04131f5
.Pseudo-versions never need to be typed by hand. Many commands accept a commit hash or a branch name and will translate it into a pseudo-version (or tagged version if available) automatically. For example:
go get -d example.com/mod@master go list -m -json example.com/mod@abcd1234
Starting with major version 2, module paths must have a major version suffix like /v2
that matches the major version. For example, if a module has the path example.com/mod
at v1.0.0
, it must have the path example.com/mod/v2
at version v2.0.0
.
Major version suffixes implement the import compatibility rule:
If an old package and a new package have the same import path, the new package must be backwards compatible with the old package.
By definition, packages in a new major version of a module are not backwards compatible with the corresponding packages in the previous major version. Consequently, starting with v2
, packages need new import paths. This is accomplished by adding a major version suffix to the module path. Since the module path is a prefix of the import path for each package within the module, adding the major version suffix to the module path provides a distinct import path for each incompatible version.
Major version suffixes are not allowed at major versions v0
or v1
. There is no need to change the module path between v0
and v1
because v0
versions are unstable and have no compatibility guarantee. Additionally, for most modules, v1
is backwards compatible with the last v0
version; a v1
version acts as a commitment to compatibility, rather than an indication of incompatible changes compared with v0
.
As a special case, modules paths starting with gopkg.in/
must always have a major version suffix, even at v0
and v1
. The suffix must start with a dot rather than a slash (for example, gopkg.in/yaml.v2
).
Major version suffixes let multiple major versions of a module coexist in the same build. This may be necessary due to a diamond dependency problem. Ordinarily, if a module is required at two different versions by transitive dependencies, the higher version will be used. However, if the two versions are incompatible, neither version will satisfy all clients. Since incompatible versions must have different major version numbers, they must also have different module paths due to major version suffixes. This resolves the conflict: modules with distinct suffixes are treated as separate modules, and their packages—even packages in same subdirectory relative to their module roots—are distinct.
Many Go projects released versions at v2
or higher without using a major version suffix before migrating to modules (perhaps before modules were even introduced). These versions are annotated with a +incompatible
build tag (for example, v2.0.0+incompatible
). See Compatibility with non-module repositories for more information.
When the go
command loads a package using a package path, it needs to determine which module provides the package.
The go
command starts by searching the build list for modules with paths that are prefixes of the package path. For example, if the package example.com/a/b
is imported, and the module example.com/a
is in the build list, the go
command will check whether example.com/a
contains the package, in the directory b
. At least one file with the .go
extension must be present in a directory for it to be considered a package. Build constraints are not applied for this purpose. If exactly one module in the build list provides the package, that module is used. If two or more modules provide the package, an error is reported. If no modules provide the package, the go
command will attempt to find a new module (unless the flags -mod=readonly
or -mod=vendor
are used, in which case, an error is reported).
When the go
command looks up a new module for a package path, it checks the GOPROXY
environment variable, which is a comma-separated list of proxy URLs or the keywords direct
or off
. A proxy URL indicates the go
command should contact a module proxy using the GOPROXY
protocol. direct
indicates that the go
command should communicate with a version control system. off
indicates that no communication should be attempted. The GOPRIVATE
and GONOPROXY
environment variables can also be used to control this behavior.
For each entry in the GOPROXY
list, the go
command requests the latest version of each module path that might provide the package (that is, each prefix of the package path). For each successfully requested module path, the go
command will download the module at the latest version and check whether the module contains the requested package. If one or more modules contain the requested package, the module with the longest path is used. If one or more modules are found but none contain the requested package, an error is reported. If no modules are found, the go
command tries the next entry in the GOPROXY
list. If no entries are left, an error is reported.
For example, suppose the go
command is looking for a module that provides the package golang.org/x/net/html
, and GOPROXY
is set to https://corp.example.com,https://proxy.golang.org
. The go
command may make the following requests:
https://corp.example.com/
(in parallel):golang.org/x/net/html
golang.org/x/net
golang.org/x
golang.org
https://proxy.golang.org/
, if all requests to https://corp.example.com/
have failed with 404 or 410:golang.org/x/net/html
golang.org/x/net
golang.org/x
golang.org
After a suitable module has been found, the go
command will add a new requirement with the new module‘s path and version to the main module’s go.mod
file. This ensures that when the same package is loaded in the future, the same module will be used at the same version. If the resolved package is not imported by a package in the main module, the new requirement will have an // indirect
comment.
go.mod
filesA module is defined by a UTF-8 encoded text file named go.mod
in its root directory. The go.mod
file is line-oriented. Each line holds a single directive, made up of a keyword followed by arguments. For example:
module example.com/my/thing go 1.12 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
The leading keyword can be factored out of adjacent lines to create a block, like in Go imports.
require ( example.com/new/thing/v2 v2.3.4 example.com/old/thing v1.2.3 )
The go.mod
file is designed to be human readable and machine writable. The go
command provides several subcommands that change go.mod
files. For example, go get
can upgrade or downgrade specific dependencies. Commands that load the module graph will automatically update go.mod
when needed. go mod edit
can perform low-level edits. The golang.org/x/mod/modfile
package can be used by Go programs to make the same changes programmatically.
When a go.mod
file is parsed, its content is broken into a sequence of tokens. There are several kinds of tokens: whitespace, comments, punctuation, keywords, identifiers, and strings.
White space consists of spaces (U+0020), tabs (U+0009), carriage returns (U+000D), and newlines (U+000A). White space characters other than newlines have no effect except to separate tokens that would otherwise be combined. Newlines are significant tokens.
Comments start with //
and run to the end of a line. /* */
comments are not allowed.
Punctuation tokens include (
, )
, and =>
.
Keywords distinguish different kinds of directives in a go.mod
file. Allowed keywords are module
, go
, require
, replace
, and exclude
.
Identifiers are sequences of non-whitespace characters, such as module paths or semantic versions.
Strings are quoted sequences of characters. There are two kinds of strings: interpreted strings beginning and ending with quotation marks ("
, U+0022) and raw strings beginning and ending with grave accents (<, U+0060). Interpreted strings may contain escape sequences consisting of a backslash (\
, U+005C) followed by another character. An escaped quotation mark (\"
) does not terminate an interpreted string. The unquoted value of an interpreted string is the sequence of characters between quotation marks with each escape sequence replaced by the character following the backslash (for example, \"
is replaced by "
, \n
is replaced by n
). In contrast, the unquoted value of a raw string is simply the sequence of characters between grave accents; backslashes have no special meaning within raw strings.
Identifiers and strings are interchangeable in the go.mod
grammar.
Most identifiers and strings in a go.mod
file are either module paths or versions.
A module path must satisfy the following requirements:
/
, U+002F). It must not begin or end with a slash.+
, -
, .
, _
, and ~
)..
, U+002E).CON
, com1
, NuL
, and so on).If the module path appears in a require
directive and is not replaced, or if the module paths appears on the right side of a replace
directive, the go
command may need to download modules with that path, and some additional requirements must be satisfied.
.
, U+002E), and dashes (-
, U+002D); it must contain at least one dot and cannot start with a dash./vN
where N
looks numeric (ASCII digits and dots), N
must not begin with a leading zero, must not be /v1
, and must not contain any dots.gopkg.in/
, this requirement is replaced by a requirement that the path follow the gopkg.in service's conventions.Versions in go.mod
files may be canonical or non-canonical.
A canonical version starts with the letter v
, followed by a semantic version following the Semantic Versioning 2.0.0 specification. See Versions for more information.
Most other identifiers and strings may be used as non-canonical versions, though there are some restrictions to avoid problems with file systems, repositories, and module proxies. Non-canonical versions are only allowed in the main module's go.mod
file. The go
command will attempt to replace each non-canonical version with an equivalent canonical version when it automatically updates the go.mod
file.
In places where a module path is associated with a verison (as in require
, replace
, and exclude
directives), the final path element must be consistent with the version. See Major version suffixes.
go.mod
syntax is specified below using Extended Backus-Naur Form (EBNF). See the Notation section in the Go Language Specificiation for details on EBNF syntax.
GoMod = { Directive } . Directive = ModuleDirective | GoDirective | RequireDirective | ExcludeDirective | ReplaceDirective .
Newlines, identifiers, and strings are denoted with newline
, ident
, and string
, respectively.
Module paths and versions are denoted with ModulePath
and Version
.
ModulePath = ident | string . /* see restrictions above */ Version = ident | string . /* see restrictions above */
module
directiveA module
directive defines the main module's path. A go.mod
file must contain exactly one module
directive.
ModuleDirective = "module" ( ModulePath | "(" newline ModulePath newline ")" newline .
Example:
module golang.org/x/net
go
directiveA go
directive sets the expected language version for the module. The version must be a valid Go release version: a positive integer followed by a dot and a non-negative integer (for example, 1.9
, 1.14
).
The language version determines which language features are available when compiling packages in the module. Language features present in that version will be available for use. Language features removed in earlier versions, or added in later versions, will not be available. The language version does not affect build tags, which are determined by the Go release being used.
The language version is also used to enable features in the go
command. For example, automatic vendoring may be enabled with a go
version of 1.14
or higher.
A go.mod
file may contain at most one go
directive. Most commands will add a go
directive with the current Go version if one is not present.
GoDirective = "go" GoVersion newline . GoVersion = string | ident . /* valid release version; see above */
Example:
go 1.14
require
directiveA require
directive declares a minimum required version of a given module dependency. For each required module version, the go
command loads the go.mod
file for that version and incorporates the requirements from that file. Once all requirements have been loaded, the go
command resolves them using minimal version selection (MVS) to produce the build list.
The go
command automatically adds // indirect
comments for some requirements. An // indirect
comment indicates that no package from the required module is directly imported by any package in the main module. The go
command adds an indirect requirement when the selected version of a module is higher than what is already implied (transitively) by the main module's other dependencies. That may occur because of an explicit upgrade (go get -u
), removal of some other dependency that previously imposed the requirement (go mod tidy
), or a dependency that imports a package without a corresponding requirement in its own go.mod
file (such as a dependency that lacks a go.mod
file altogether).
RequireDirective = "require" ( RequireSpec | "(" newline { RequireSpec } ")" newline ) . RequireSpec = ModulePath Version newline .
Example:
require golang.org/x/net v1.2.3 require ( golang.org/x/crypto v1.4.5 // indirect golang.org/x/text v1.6.7 )
exclude
directiveAn exclude
directive prevents a module version from being loaded by the go
command. If an excluded version is referenced by a require
directive in a go.mod
file, the go
command will list available versions for the module (as shown with go list -m -versions
) and will load the next higher non-excluded version instead. Both release and pre-release versions are considered for this purpose, but pseudo-versions are not. If there are no higher versions, the go
command will report an error. Note that this may change in Go 1.16.
exclude
directives only apply in the main module's go.mod
file and are ignored in other modules. See Minimal version selection for details.
ExcludeDirective = "exclude" ( ExcludeSpec | "(" newline { ExcludeSpec } ")" ) . ExcludeSpec = ModulePath Version newline .
Example:
exclude golang.org/x/net v1.2.3 exclude ( golang.org/x/crypto v1.4.5 golang.org/x/text v1.6.7 )
replace
directiveA replace
directive replaces the contents of a specific version of a module, or all versions of a module, with contents found elsewhere. The replacement may be specified with either another module path and version, or a platform-specific file path.
If a version is present on the left side of the arrow (=>
), only that specific version of the module is replaced; other versions will be accessed normally. If the left version is omitted, all versions of the module are replaced.
If the path on the right side of the arrow is an absolute or relative path (beginning with ./
or ../
), it is interpreted as the local file path to the replacement module root directory, which must contain a go.mod
file. The replacement version must be omitted in this case.
If the path on the right side is not a local path, it must be a valid module path. In this case, a version is required. The same module version must not also appear in the build list.
Regardless of whether a replacement is specified with a local path or module path, if the replacement module has a go.mod
file, its module
directive must match the module path it replaces.
replace
directives only apply in the main module's go.mod
file and are ignored in other modules. See Minimal version selection for details.
ReplaceDirective = "replace" ( ReplaceSpec | "(" newline { ReplaceSpec } ")" newline ")" ) . ReplaceSpec = ModulePath [ Version ] "=>" FilePath newline | ModulePath [ Version ] "=>" ModulePath Version newline . FilePath = /* platform-specific relative or absolute file path */
Example:
replace golang.org/x/net v1.2.3 => example.com/fork/net v1.4.5 replace ( golang.org/x/net v1.2.3 => example.com/fork/net v1.4.5 golang.org/x/net => example.com/fork/net v1.4.5 golang.org/x/net v1.2.3 => ./fork/net golang.org/x/net => ./fork/net )
The go
command automatically updates go.mod
when it uses the module graph if some information is missing or go.mod
doesn't accurately reflect reality. For example, consider this go.mod
file:
module example.com/M require ( example.com/A v1 example.com/B v1.0.0 example.com/C v1.0.0 example.com/D v1.2.3 example.com/E dev ) exclude example.com/D v1.2.3
The update rewrites non-canonical version identifiers to canonical semver form, so example.com/A
's v1
becomes v1.0.0
, and example.com/E
's dev
becomes the pseudo-version for the latest commit on the dev
branch, perhaps v0.0.0-20180523231146-b3f5c0f6e5f1
.
The update modifies requirements to respect exclusions, so the requirement on the excluded example.com/D v1.2.3
is updated to use the next available version of example.com/D
, perhaps v1.2.4
or v1.3.0
.
The update removes redundant or misleading requirements. For example, if example.com/A v1.0.0
itself requires example.com/B v1.2.0
and example.com/C v1.0.0
, then go.mod
's requirement of example.com/B v1.0.0
is misleading (superseded by example.com/A
's need for v1.2.0
), and its requirement of example.com/C v1.0.0
is redundant (implied by example.com/A
's need for the same version), so both will be removed. If the main module contains packages that directly import packages from example.com/B
or example.com/C
, then the requirements will be kept but updated to the actual versions being used.
Finally, the update reformats the go.mod
in a canonical formatting, so that future mechanical changes will result in minimal diffs. The go
command will not update go.mod
if only formatting changes are needed.
Because the module graph defines the meaning of import statements, any commands that load packages also use and therefore update go.mod
, including go build
, go get
, go install
, go list
, go test
, go mod graph
, go mod tidy
, and go mod why
.
The -mod=readonly
flag prevents commands from automatically updating go.mod
. However, if a command needs to perform an action that would update to go.mod
, it will report an error. For example, if go build
is asked to build a package not provided by any module in the build list, go build
will report an error instead of looking up the module and updating requirements in go.mod
.
Go uses an algorithm called Minimal version selection (MVS) to select a set of module versions to use when building packages. MVS is described in detail in Minimal Version Selection by Russ Cox.
Conceptually, MVS operates on a directed graph of modules, specified with go.mod
files. Each vertex in the graph represents a module version. Each edge represents a minimum required version of a dependency, specified using a require
directive. replace
and exclude
directives in the main module's go.mod
file modify the graph.
MVS produces the build list as output, the list of module versions used for a build.
MVS starts at the main module (a special vertex in the graph that has no version) and traverses the graph, tracking the highest required version of each module. At the end of the traversal, the highest required versions comprise the build list: they are the minimum versions that satisfy all requirements.
The build list may be inspected with the command go list -m all
. Unlike other dependency management systems, the build list is not saved in a “lock” file. MVS is deterministic, and the build list doesn't change when new versions of dependencies are released, so MVS is used to compute it at the beginning of every module-aware command.
Consider the example in the diagram below. The main module requires module A at version 1.2 or higher and module B at version 1.2 or higher. A 1.2 and B 1.2 require C 1.3 and C 1.4, respectively. C 1.3 and C 1.4 both require D 1.2.
MVS visits and loads the go.mod
file for each of the module versions highlighted in blue. At the end of the graph traversal, MVS returns a build list containing the bolded versions: A 1.2, B 1.2, C 1.4, and D 1.2. Note that higher versions of B and D are available but MVS does not select them, since nothing requires them.
The content of a module (including its go.mod
file) may be replaced using a replace
directive in the the main module's go.mod
file. A replace
directive may apply to a specific version of a module or to all versions of a module.
Replacements change the module graph, since a replacement module may have different dependencies than replaced versions.
Consider the example below, where C 1.4 has been replaced with R. R depends on D 1.3 instead of D 1.2, so MVS returns a build list containing A 1.2, B 1.2, C 1.4 (replaced with R), and D 1.3.
A module may also be excluded at specific versions using an exclude
directive in the main module's go.mod
file.
Exclusions also change the module graph. When a version is excluded, it is removed from the module graph, and requirements on it are redirected to the next higher version.
Consider the example below. C 1.3 has been excluded. MVS will act as if A 1.2 required C 1.4 (the next higher version) instead of C 1.3.
The go get
command may be used to upgrade a set of modules. To perform an upgrade, the go
command changes the module graph before running MVS by adding edges from visited versions to upgraded versions.
Consider the example below. Module B may be upgraded from 1.2 to 1.3, C may be upgraded from 1.3 to 1.4, and D may be upgraded from 1.2 to 1.3.
Upgrades (and downgrades) may add or remove indirect dependencies. In this case, E 1.1 and F 1.1 appear in the build list after the upgrade, since E 1.1 is required by B 1.3.
To preserve upgrades, the go
command updates the requirements in go.mod
. It will change the requirement on B to version 1.3. It will also add requirements on C 1.4 and D 1.3 with // indirect
comments, since those versions would not be selected otherwise.
The go get
command may also be used to downgrade a set of modules. To perform a downgrade, the go
command changes the module graph by removing versions above the downgraded versions. It also removes versions of other modules that depend on removed versions, since they may not be compatible with the downgraded versions of their dependencies. If the main module requires a module version removed by downgrading, the requirement is changed to a previous version that has not been removed. If no previous version is available, the requirement is dropped.
Consider the example below. Suppose that a problem was found with C 1.4, so we downgrade to C 1.3. C 1.4 is removed from the module graph. B 1.2 is also removed, since it requires C 1.4 or higher. The main module's requirement on B is changed to 1.1.
go get
can also remove dependencies entirely, using an @none
suffix after an argument. This works similarly to a downgrade. All versions of the named module are removed from the module graph.
To ensure a smooth transition from GOPATH
to modules, the go
command can download and build packages in module-aware mode from repositories that have not migrated to modules by adding a go.mod
file.
When the go
command downloads a module at a given version directly from a repository, it looks up a repository URL for the module path, maps the version to a revision within the repository, then extracts an archive of the repository at that revision. If the module's path is equal to the repository root path, and the repository root directory does not contain a go.mod
file, the go
command synthesizes a go.mod
file in the module cache that contains a module
directive and nothing else. Since synthetic go.mod
files do not contain require
directives for their dependencies, other modules that depend on them may need additional require
directives (with // indirect
comments) to ensure each dependency is fetched at the same version on every build.
When the go
command downloads a module from a proxy, it downloads the go.mod
file separately from the rest of the module content. The proxy is expected to serve a synthetic go.mod
file if the original module didn't have one.
+incompatible
versionsA module released at major version 2 or higher must have a matching major version suffix on its module path. For example, if a module is released at v2.0.0
, its path must have a /v2
suffix. This allows the go
command to treat multiple major versions of a project as distinct modules, even if they're developed in the same repository.
The major version suffix requirement was introduced when module support was added to the go
command, and many repositories had already tagged releases with major version 2
or higher before that. To maintain compatibility with these repositories, the go
command adds an +incompatible
suffix to versions with major version 2 or higher without a go.mod
file. +incompatible
indicates that a version is part of the same module as versions with lower major version numbers; consequently, the go
command may automatically upgrade to higher +incompatible
versions even though it may break the build.
Consider the example requirement below:
require example.com/m v4.1.2+incompatible
The version v4.1.2+incompatible
refers to the semantic version tag v4.1.2
in the repository that provides the module example.com/m
. The module must be in the repository root directory (that is, the repository root path must also be example.com/m
), and a go.mod
file must not be present. The module may have versions with lower major version numbers like v1.5.2
, and the go
command may upgrade automatically to v4.1.2+incompatible
from those versions (see minimal version selection (MVS) for information on how upgrades work).
A repository that migrates to modules after version v2.0.0
is tagged should usually release a new major version. In the example above, the author should create a module with the path example.com/m/v5
and should release version v5.0.0
. The author should also update imports of packages in the module to use the prefix example.com/m/v5
instead of example.com/m
. See Go Modules: v2 and Beyond for a more detailed example.
Note that the +incompatible
suffix should not appear on a tag in a repository; a tag like v4.1.2+incompatible
will be ignored. The suffix only appears in versions used by the go
command. See Mapping versions to commits for details on the distinction between versions and tags.
Note also that the +incompatible
suffix may appear on pseudo-versions. For example, v2.0.1-20200722182040-012345abcdef+incompatible
may be a valid pseudo-version.
A module released at major version 2 or higher is required to have a major version suffix on its module path. The module may or may not be developed in a major version subdirectory within its repository. This has implications for packages that import packages within the module when building GOPATH
mode.
Normally in GOPATH
mode, a package is stored in a directory matching its repository's root path joined with its diretory within the repository. For example, a package in the repository with root path example.com/repo
in the subdirectory sub
would be stored in $GOPATH/src/example.com/repo/sub
and would be imported as example.com/repo/sub
.
For a module with a major version suffix, one might expect to find the package example.com/repo/v2/sub
in the directory $GOPATH/src/example.com/repo/v2/sub
. This would require the module to be developed in the v2
subdirectory of its repository. The go
command supports this but does not require it (see Mapping versions to commits).
If a module is not developed in a major version subdirectory, then its directory in GOPATH
will not contain the major version suffix, and its packages may be imported without the major version suffix. In the example above, the package would be found in the directory $GOPATH/src/example.com/repo/sub
and would be imported as example.com/repo/sub
.
This creates a problem for packages intended to be built in both module mode and GOPATH
mode: module mode requires a suffix, while GOPATH
mode does not.
To fix this, minimal module compatibility was added in Go 1.11 and was backported to Go 1.9.7 and 1.10.3. When an import path is resolved to a directory in GOPATH
mode:
$modpath/$vn/$dir
where:$modpath
is a valid module path,$vn
is a major version suffix,$dir
is a possibly empty subdirectory,$modpath/$vn/$dir
is not present in any relevant vendor
directory.go.mod
file is present in the same directory as the importing file or in any parent directory up to the $GOPATH/src
root,$GOPATH[i]/src/$modpath/$vn/$suffix
directory exists (for any root $GOPATH[i]
),$GOPATH[d]/src/$modpath/go.mod
exists (for some root $GOPATH[d]
) and declares the module path as $modpath/$vn
,$modpath/$vn/$dir
is resolved to the directory $GOPATH[d]/src/$modpath/$dir
.This rules allow packages that have been migrated to modules to import other packages that have been migrated to modules when built in GOPATH
mode even when a major version subdirectory was not used.
Most go
commands may run in Module-aware mode or GOPATH
mode. In module-aware mode, the go
command uses go.mod
files to find versioned dependencies, and it typically loads packages out of the module cache, downloading modules if they are missing. In GOPATH
mode, the go
command ignores modules; it looks in vendor
directories and in GOPATH
to find dependencies.
Module-aware mode is active by default whenever a go.mod
file is found in the current directory or in any parent directory. For more fine-grained control, the GO111MODULE
environment variable may be set to one of three values: on
, off
, or auto
.
GO111MODULE=off
, the go
command ignores go.mod
files and runs in GOPATH
mode.GO111MODULE=on
, the go
command runs in module-aware mode, even when no go.mod
file is present. Not all commands work without a go.mod
file: see Module commands outside a module.GO111MODULE=auto
or is unset, the go
command runs in module-aware mode if a go.mod
file is present in the current directory or any parent directory (the default behavior).In module-aware mode, GOPATH
no longer defines the meaning of imports during a build, but it still stores downloaded dependencies (in GOPATH/pkg/mod
; see Module cache) and installed commands (in GOPATH/bin
, unless GOBIN
is set).
All commands that load information about packages are module-aware. This includes:
go build
go fix
go generate
go get
go install
go list
go run
go test
go vet
When run in module-aware mode, these commands use go.mod
files to interpret import paths listed on the command line or written in Go source files. These commands accept the following flags, common to all module commands.
-mod
flag controls whether go.mod
may be automatically updated and whether the vendor
directory is used.-mod=mod
tells the go
command to ignore the vendor directory and to automatically update go.mod
, for example, when an imported package is not provided by any known module.-mod=readonly
tells the go
command to ignore the vendor
directory and to report an error if go.mod
needs to be updated.-mod=vendor
tells the go
command to use the vendor
directory. In this mode, the go
command will not use the network or the module cache.go
version in go.mod
is 1.14
or higher and a vendor
directory is present, the go
command will act as if -mod=vendor
were used. Otherwise, the go
command will act as if -mod=mod
were used.-modcacherw
flag instructs the go
command to create new directories in the module cache with read-write permissions instead of making them read-only. When this flag is used consistently (typically by setting GOFLAGS=-modcacherw
in the environment or by running go env -w GOFLAGS=-modcacherw
), the module cache may be deleted with commands like rm -r
without changing permissions first. The go clean -modcache
command may be used to delete the module cache, whether or not -modcacherw
was used.-modfile=file.mod
flag instructs the go
command to read (and possibly write) an alternate file instead of go.mod
in the module root directory. The file's name must end with .mod
. A file named go.mod
must still be present in order to determine the module root directory, but it is not accessed. When -modfile
is specified, an alternate go.sum
file is also used: its path is derived from the -modfile
flag by trimming the .mod
extension and appending .sum
.When using modules, the go
command typically satisfies dependencies by downloading modules from their sources into the module cache, then loading packages from those downloaded copies. Vendoring may be used to allow interoperation with older versions of Go, or to ensure that all files used for a build are stored in a single file tree.
The go mod vendor
command constructs a directory named vendor
in the main module's root directory containing copies of all packages needed to build and test packages in the main module. Packages that are only imported by tests of packages outside the main module are not included. As with go mod tidy
and other module commands, build constraints except for ignore
are not considered when constructing the vendor
directory.
go mod vendor
also creates the file vendor/modules.txt
that contains a list of vendored packages and the module versions they were copied from. When vendoring is enabled, this manifest is used as a source of module version information, as reported by go list -m
and go version -m
. When the go
command reads vendor/modules.txt
, it checks that the module versions are consistent with go.mod
. If go.mod
has changed since vendor/modules.txt
was generated, the go
command will report an error. go mod vendor
should be run again to update the vendor
directory.
If the vendor
directory is present in the main module‘s root directory, it will be used automatically if the go
version in the main module’s go.mod
file is 1.14
or higher. To explicitly enable vendoring, invoke the go
command with the flag -mod=vendor
. To disable vendoring, use the flag -mod=mod
.
When vendoring is enabled, build commands like go build
and go test
load packages from the vendor
directory instead of accessing the network or the local module cache. The go list -m
command only prints information about modules listed in go.mod
. go mod
commands such as go mod download
and go mod tidy
do not work differently when vendoring is enabled and will still download modules and access the module cache. go get
also does not work differently when vendoring is enabled.
Unlike vendoring in GOPATH
, the go
command ignores vendor directories in locations other than the main module's root directory.
go get
Usage:
go get [-d] [-t] [-u] [build flags] [packages]
Examples:
# Install the latest version of a tool. $ go get golang.org/x/tools/cmd/goimports # Upgrade a specific module. $ go get -d golang.org/x/net # Upgrade modules that provide packages imported by packages in the main module. $ go get -d -u ./... # Upgrade or downgrade to a specific version of a module. $ go get -d golang.org/x/text@v0.3.2 # Update to the commit on the module's master branch. $ go get -d golang.org/x/text@master # Remove a dependency on a module and downgrade modules that require it # to versions that don't require it. $ go get -d golang.org/x/text@none
The go get
command updates module dependencies in the go.mod
file for the main module, then builds and installs packages listed on the command line.
The first step is to determine which modules to update. go get
accepts a list of packages, package patterns, and module paths as arguments. If a package argument is specified, go get
updates the module that provides the package. If a package pattern is specified (for example, all
or a path with a ...
wildcard), go get
expands the pattern to a set of packages, then updates the modules that provide the packages. If an argument names a module but not a package (for example, the module golang.org/x/net
has no package in its root directory), go get
will update the module but will not build a package. If no arguments are specified, go get
acts as if .
were specified (the package in the current directory); this may be used together with the -u
flag to update modules that provide imported packages.
Each argument may include a version query suffix indicating the desired version, as in go get golang.org/x/text@v0.3.0
. A version query suffix consists of an @
symbol followed by a version query, which may indicate a specific version (v0.3.0
), a version prefix (v0.3
), a branch or tag name (master
), a revision (1234abcd
), or one of the special queries latest
, upgrade
, patch
, or none
. If no version is given, go get
uses the @upgrade
query.
Once go get
has resolved its arguments to specific modules and versions, go get
will add, change, or remove require
directives in the main module's go.mod
file to ensure the modules remain at the desired versions in the future. Note that required versions in go.mod
files are minimum versions and may be increased automatically as new dependencies are added. See Minimal version selection (MVS) for details on how versions are selected and conflicts are resolved by module-aware commands.
Other modules may be upgraded when a module named on the command line is added, upgraded, or downgraded if the new version of the named module requires other modules at higher versions. For example, suppose module example.com/a
is upgraded to version v1.5.0
, and that version requires module example.com/b
at version v1.2.0
. If module example.com/b
is currently required at version v1.1.0
, go get example.com/a@v1.5.0
will also upgrade example.com/b
to v1.2.0
.
Other modules may be downgraded when a module named on the command line is downgraded or removed. To continue the above example, suppose module example.com/b
is downgraded to v1.1.0
. Module example.com/a
would also be downgraded to a version that requires example.com/b
at version v1.1.0
or lower.
A module requirement may be removed using the version suffix @none
. This is a special kind of downgrade. Modules that depend on the removed module will be downgraded or removed as needed. A module requirement may be removed even if one or more of its packages are imported by packages in the main module. In this case, the next build command may add a new module requirement.
If a module is needed at two different versions (specified explicitly in command line arguments or to satisfy upgrades and downgrades), go get
will report an error.
After go get
updates the go.mod
file, it builds the packages named on the command line. Executables will be installed in the directory named by the GOBIN
environment variable, which defaults to $GOPATH/bin
or $HOME/go/bin
if the GOPATH
environment variable is not set.
go get
supports the following flags:
-d
flag tells go get
not to build or install packages. When -d
is used, go get
will only manage dependencies in go.mod
.-u
flag tells go get
to upgrade modules providing packages imported directly or indirectly by packages named on the command line. Each module selected by -u
will be upgraded to its latest version unless it is already required at a higher version (a pre-release).-u=patch
flag (not -u patch
) also tells go get
to upgrade dependencies, but go get
will upgrade each dependency to the latest patch version (similar to the @patch
version query).-t
flag tells go get
to consider modules needed to build tests of packages named on the command line. When -t
and -u
are used together, go get
will update test dependencies as well.-insecure
flag should no longer be used. It permits go get
to resolve custom import paths and fetch from repositories and module proxies using insecure schemes such as HTTP. The GOINSECURE
environment variable provides more fine-grained control and should be used instead.go list -m
Usage:
go list -m [-u] [-versions] [list flags] [modules]
Example:
$ go list -m all $ go list -m -versions example.com/m $ go list -m -json example.com/m@latest
The -m
flag causes go list
to list modules instead of packages. In this mode, the arguments to go list
may be modules, module patterns (containing the ...
wildcard), version queries, or the special pattern all
, which matches all modules in the build list. If no arguments are specified, the main module is listed.
When listing modules, the -f
flag still specifies a format template applied to a Go struct, but now a Module
struct:
type Module struct { Path string // module path Version string // module version Versions []string // available module versions (with -versions) Replace *Module // replaced by this module Time *time.Time // time version was created Update *Module // available update, if any (with -u) Main bool // is this the main module? Indirect bool // is this module only an indirect dependency of main module? Dir string // directory holding files for this module, if any GoMod string // path to go.mod file for this module, if any GoVersion string // go version used in module Error *ModuleError // error loading module } type ModuleError struct { Err string // the error itself }
The default output is to print the module path and then information about the version and replacement if any. For example, go list -m all
might print:
example.com/main/module golang.org/x/text v0.3.0 => /tmp/text rsc.io/pdf v0.1.1
The Module
struct has a String
method that formats this line of output, so that the default format is equivalent to -f '{{.String}}'
.
Note that when a module has been replaced, its Replace
field describes the replacement module module, and its Dir
field is set to the replacement module's source code, if present. (That is, if Replace
is non-nil, then Dir
is set to Replace.Dir
, with no access to the replaced source code.)
The -u
flag adds information about available upgrades. When the latest version of a given module is newer than the current one, list -u
sets the module‘s Update
field to information about the newer module. The module’s String
method indicates an available upgrade by formatting the newer version in brackets after the current version. For example, go list -m -u all
might print:
example.com/main/module golang.org/x/text v0.3.0 [v0.4.0] => /tmp/text rsc.io/pdf v0.1.1 [v0.1.2]
(For tools, go list -m -u -json all
may be more convenient to parse.)
The -versions
flag causes list
to set the module's Versions
field to a list of all known versions of that module, ordered according to semantic versioning, lowest to highest. The flag also changes the default output format to display the module path followed by the space-separated version list.
The template function module
takes a single string argument that must be a module path or query and returns the specified module as a Module
struct. If an error occurs, the result will be a Module
struct with a non-nil Error
field.
go mod download
Usage:
go mod download [-json] [-x] [modules]
Example:
$ go mod download $ go mod download golang.org/x/mod@v0.2.0
The go mod download
command downloads the named modules into the module cache. Arguments can be module paths or module patterns selecting dependencies of the main module or version queries of the form path@version
. With no arguments, download
applies to all dependencies of the main module.
The go
command will automatically download modules as needed during ordinary execution. The go mod download
command is useful mainly for pre-filling the module cache or for loading data to be served by a module proxy.
By default, download
writes nothing to standard output. It prints progress messages and errors to standard error.
The -json
flag causes download
to print a sequence of JSON objects to standard output, describing each downloaded module (or failure), corresponding to this Go struct:
type Module struct { Path string // module path Version string // module version Error string // error loading module Info string // absolute path to cached .info file GoMod string // absolute path to cached .mod file Zip string // absolute path to cached .zip file Dir string // absolute path to cached source root directory Sum string // checksum for path, version (as in go.sum) GoModSum string // checksum for go.mod (as in go.sum) }
The -x
flag causes download
to print the commands download
executes to standard error.
go mod edit
Usage:
go mod edit [editing flags] [-fmt|-print|-json] [go.mod]
Example:
# Add a replace directive. $ go mod edit -replace example.com/a@v1.0.0=./a # Remove a replace directive. $ go mod edit -dropreplace example.com/a@v1.0.0 # Set the go version, add a requirement, and print the file # instead of writing it to disk. $ go mod edit -go=1.14 -require=example.com/m@v1.0.0 -print # Format the go.mod file. $ go mod edit -fmt # Format and print a different .mod file. $ go mod edit -print tools.mod # Print a JSON representation of the go.mod file. $ go mod edit -json
The go mod edit
command provides a command-line interface for editing and formatting go.mod
files, for use primarily by tools and scripts. go mod edit
reads only one go.mod
file; it does not look up information about other modules. By default, go mod edit
reads and writes the go.mod
file of the main module, but a different target file can be specified after the editing flags.
The editing flags specify a sequence of editing operations.
-module
flag changes the module‘s path (the go.mod
file’s module line).-go=version
flag sets the expected Go language version.-require=path@version
and -droprequire=path
flags add and drop a requirement on the given module path and version. Note that -require
overrides any existing requirements on path
. These flags are mainly for tools that understand the module graph. Users should prefer go get path@version
or go get path@none
, which make other go.mod
adjustments as needed to satisfy constraints imposed by other modules. See go get
.-exclude=path@version
and -dropexclude=path@version
flags add and drop an exclusion for the given module path and version. Note that -exclude=path@version
is a no-op if that exclusion already exists.-replace=old[@v]=new[@v]
flag adds a replacement of the given module path and version pair. If the @v
in old@v
is omitted, a replacement without a version on the left side is added, which applies to all versions of the old module path. If the @v
in new@v
is omitted, the new path should be a local module root directory, not a module path. Note that -replace
overrides any redundant replacements for old[@v]
, so omitting @v
will drop replacements for specific versions.-dropreplace=old[@v]
flag drops a replacement of the given module path and version pair. If the @v
is provided, a replacement with the given version is dropped. An existing replacement without a version on the left side may still replace the module. If the @v
is omitted, a replacement without a version is dropped.The editing flags may be repeated. The changes are applied in the order given.
go mod edit
has additional flags that control its output.
-fmt
flag reformats the go.mod
file without making other changes. This reformatting is also implied by any other modifications that use or rewrite the go.mod
file. The only time this flag is needed is if no other flags are specified, as in go mod edit -fmt
.-print
flag prints the final go.mod
in its text format instead of writing it back to disk.-json
flag prints the final go.mod
in JSON format instead of writing it back to disk in text format. The JSON output corresponds to these Go types:type Module struct { Path string Version string } type GoMod struct { Module Module Go string Require []Require Exclude []Module Replace []Replace } type Require struct { Path string Version string Indirect bool } type Replace struct { Old Module New Module }
Note that this only describes the go.mod
file itself, not other modules referred to indirectly. For the full set of modules available to a build, use go list -m -json all
. See go list -m
.
For example, a tool can obtain the go.mod
file as a data structure by parsing the output of go mod edit -json
and can then make changes by invoking go mod edit
with -require
, -exclude
, and so on.
Tools may also use the package golang.org/x/mod/modfile
to parse, edit, and format go.mod
files.
go mod init
Usage:
go mod init [module-path]
Example:
go mod init go mod init example.com/m
The go mod init
command initializes and writes a new go.mod
file in the current directory, in effect creating a new module rooted at the current directory. The go.mod
file must not already exist.
init
accepts one optional argument, the module path for the new module. See Module paths for instructions on choosing a module path. If the module path argument is omitted, init
will attempt to infer the module path using import comments in .go
files, vendoring tool configuration files, and the current directory (if in GOPATH
).
If a configuration file for a vendoring tool is present, init
will attempt to import module requirements from it. init
supports the following configuration files.
GLOCKFILE
(Glock)Godeps/Godeps.json
(Godeps)Gopkg.lock
(dep)dependencies.tsv
(godeps)glide.lock
(glide)vendor.conf
(trash)vendor.yml
(govend)vendor/manifest
(gvt)vendor/vendor.json
(govendor)Vendoring tool configuration files can't always be translated with perfect fidelity. For example, if multiple packages within the same repository are imported at different versions, and the repository only contains one module, the imported go.mod
can only require the module at one version. You may wish to run go list -m all
to check all versions in the build list, and go mod tidy
to add missing requirements and to drop unused requirements.
go mod tidy
Usage:
go mod tidy [-v]
go mod tidy
ensures that the go.mod
file matches the source code in the module. It adds any missing module requirements necessary to build the current module‘s packages and dependencies, and it removes requirements on modules that don’t provide any relevant packages. It also adds any missing entries to go.sum
and removes unnecessary entries.
The -v
flag causes go mod tidy
to print information about removed modules to standard error.
go mod tidy
works by loading all of the packages in the main module and all of the packages they import, recursively. This includes packages imported by tests (including tests in other modules). go mod tidy
acts as if all build tags are enabled, so it will consider platform-specific source files and files that require custom build tags, even if those source files wouldn't normally be built. There is one exception: the ignore
build tag is not enabled, so a file with the build constraint // +build ignore
will not be considered. Note that go mod tidy
will not consider packages in the main module in directories named testdata
or with names that start with .
or _
unless those packages are explicitly imported by other packages.
Once go mod tidy
has loaded this set of packages, it ensures that each module that provides one or more packages either has a require
directive in the main module‘s go.mod
file or is required by another required module. go mod tidy
will add a requirement on the latest version on each missing module (see Version queries for the definition of the latest
version). go mod tidy
will remove require
directives for modules that don’t provide any packages in the set described above.
go mod tidy
may also add or remove // indirect
comments on require
directives. An // indirect
comment denotes a module that does not provide packages imported by packages in the main module. These requirements will be present if the module that imports packages in the indirect dependency has no go.mod
file. They may also be present if the indirect dependency is required at a higher version than is implied by the module graph; this usually happens after running a command like go get -u ./...
.
go mod vendor
Usage:
go mod vendor [-v]
The go mod vendor
command constructs a directory named vendor
in the main module's root directory that contains copies of all packages needed to support builds and tests of packages in the main module. Packages that are only imported by tests of packages outside the main module are not included. As with go mod tidy
and other module commands, build constraints except for ignore
are not considered when constructing the vendor
directory.
When vendoring is enabled, the go
command will load packages from the vendor
directory instead of downloading modules from their sources into the module cache and using packages those downloaded copies. See Vendoring for more information.
go mod vendor
also creates the file vendor/modules.txt
that contains a list of vendored packages and the module versions they were copied from. When vendoring is enabled, this manifest is used as a source of module version information, as reported by go list -m
and go version -m
. When the go
command reads vendor/modules.txt
, it checks that the module versions are consistent with go.mod
. If go.mod
changed since vendor/modules.txt
was generated, go mod vendor
should be run again.
Note that go mod vendor
removes the vendor
directory if it exists before re-constructing it. Local changes should not be made to vendored packages. The go
command does not check that packages in the vendor
directory have not been modified, but one can verify the integrity of the vendor
directory by running go mod vendor
and checking that no changes were made.
The -v
flag causes go mod vendor
to print the names of vendored modules and packages to standard error.
go mod verify
Usage:
go mod verify
go mod verify
checks that dependencies of the main module stored in the module cache have not been modified since they were downloaded. To perform this check, go mod verify
hashes each downloaded module .zip
file and extracted directory, then compares those hashes with a hash recorded when the module was first downloaded. go mod verify
checks each module in the build list (which may be printed with go list -m all
).
If all the modules are unmodified, go mod verify
prints “all modules verified”. Otherwise, it reports which modules have been changed and exits with a non-zero status.
Note that all module-aware commands verify that hashes in the main module's go.sum
file match hashes recorded for modules downloaded into the module cache. If a hash is missing from go.sum
(for example, because the module is being used for the first time), the go
command verifies its hash using the checksum database (unless the module path is matched by GOPRIVATE
or GONOSUMDB
). See Authenticating modules for details.
In contrast, go mod verify
checks that module .zip
files and their extracted directories have hashes that match hashes recorded in the module cache when they were first downloaded. This is useful for detecting changes to files in the module cache after a module has been downloaded and verified. go mod verify
does not download content for modules not in the cache, and it does not use go.sum
files to verify module content. However, go mod verify
may download go.mod
files in order to perform minimal version selection. It will use go.sum
to verify those files, and it may add go.sum
entries for missing hashes.
go version -m
Usage:
go version [-m] [-v] [file ...]
Example:
# Print Go version used to build go. $ go version # Print Go version used to build a specific executable. $ go version ~/go/bin/gopls # Print Go version and module versions used to build a specific executable. $ go version -m ~/go/bin/gopls # Print Go version and module versions used to build executables in a directory. $ go version -m ~/go/bin/
go version
reports the Go version used to build each executable file named on the command line.
If no files are named on the command line, go version
prints its own version information.
If a directory is named, go version
walks that directory, recursively, looking for recognized Go binaries and reporting their versions. By default, go version
does not report unrecognized files found during a directory scan. The -v
flag causes it to report unrecognized files.
The -m
flag causes go version
to print each executable's embedded module version information, when available. For each executable, go version -m
prints a table with tab-separated columns like the one below.
$ go version -m ~/go/bin/goimports /home/jrgopher/go/bin/goimports: go1.14.3 path golang.org/x/tools/cmd/goimports mod golang.org/x/tools v0.0.0-20200518203908-8018eb2c26ba h1:0Lcy64USfQQL6GAJma8BdHCgeofcchQj+Z7j0SXYAzU= dep golang.org/x/mod v0.2.0 h1:KU7oHjnv3XNWfa5COkzUifxZmxp1TyI7ImMXqFxLwvQ= dep golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=
The format of the table may change in the future. The same information may be obtained from runtime/debug.ReadBuildInfo
.
The meaning of each row in the table is determined by the word in the first column.
path
: the path of the main
package used to build the executable.mod
: the module containing the main
package. The columns are the module path, version, and sum, respectively. The main module has the version (devel)
and no sum.dep
: a module that provided one or more packages linked into the executable. Same format as mod
.=>
: a replacement for the module on the previous line. If the replacement is a local directory, only the directory path is listed (no version or sum). If the replacement is a module version, the path, version, and sum are listed, as with mod
and dep
. A replaced module has no sum.go clean -modcache
Usage:
go clean [-modcache]
The -modcache
flag causes go clean
to remove the entire module cache, including unpacked source code of versioned dependencies.
This is usually the best way to remove the module cache. By default, most files and directories in the module cache are read-only to prevent tests and editors from unintentionally changing files after they‘ve been authenticated. Unfortunately, this causes commands like rm -r
to fail, since files can’t be removed without first making their parent directories writable.
The -modcacherw
flag (accepted by go build
and other module-aware commands) causes new directories in the module cache to be writable. To pass -modcacherw
to all module-aware commands, add it to the GOFLAGS
variable. GOFLAGS
may be set in the environment or with go env -w
. For example, the command below sets it permanently:
go env -w GOFLAGS=-modcacherw
-modcacherw
should be used with caution; developers should be careful not to make changes to files in the module cache. go mod verify
may be used to check that files in the cache match hashes in the main module's go.sum
file.
Several commands allow you to specify a version of a module using a version query, which appears after an @
character following a module or package path on the command line.
Examples:
go get example.com/m@latest go mod download example.com/m@master go list -m -json example.com/m@e3702bed2
A version query may be one of the following:
v1.2.3
, which selects a specific version. See Versions for syntax.v1
or v1.2
, which selects the highest available version with that prefix.<v1.2.3
or >=v1.5.6
, which selects the nearest available version to the comparison target (the lowest version for >
and >=
, and the highest version for <
and <=
).v2
selects the latest version starting with v2
, not the branch named v2
.latest
, which selects the highest available release version. If there are no release versions, latest
selects the highest pre-release version. If there no tagged versions, latest
selects a pseudo-version for the commit at the tip of the repository's default branch.upgrade
, which is like latest
except that if the module is currently required at a higher version than the version latest
would select (for example, a pre-release), upgrade
will select the current version.patch
, which selects the latest available version with the same major and minor version numbers as the currently required version. If no version is currently required, patch
is equivalent to latest
.Except for queries for specific named versions or revisions, all queries consider available versions reported by go list -m -versions
(see go list -m
). This list contains only tagged versions, not pseudo-versions. Module versions disallowed by exclude directives in the main module's go.mod
file are not considered.
Release versions are preferred over pre-release versions. For example, if versions v1.2.2
and v1.2.3-pre
are available, the latest
query will select v1.2.2
, even though v1.2.3-pre
is higher. The <v1.2.4
query would also select v1.2.2
, even though v1.2.3-pre
is closer to v1.2.4
. If no release or pre-release version is available, the latest
, upgrade
, and patch
queries will select a pseudo-version for the commit at the tip of the repository's default branch. Other queries will report an error.
Module-aware Go commands normally run in the context of a main module defined by a go.mod
file in the working directory or a parent directory. Some commands may be run in module-aware mode without a go.mod
file by setting the GO111MODULE
environment variable to on
. Most commands work differently when no go.mod
file is present.
See Module-aware commands for information on enabling and disabling module-aware mode.
GOPROXY
protocolA module proxy is an HTTP server that can respond to GET
requests for paths specified below. The requests have no query parameters, and no specific headers are required, so even a site serving from a fixed file system (including a file://
URL) can be a module proxy.
Successful HTTP responses must have the status code 200 (OK). Redirects (3xx) are followed. Responses with status codes 4xx and 5xx are treated as errors. The error codes 404 (Not Found) and 410 (Gone) indicate that the requested module or version is not available on the proxy, but it may be found elsewhere. Error responses should have content type text/plain
with charset
either utf-8
or us-ascii
.
The go
command may be configured to contact proxies or source control servers using the GOPROXY
environment variable, which accepts a list of proxy URLs. The list may include the keywords direct
or off
(see Environment variables for details). List elements may be separated by commas (,
) or pipes (|
), which determine error fallback behavior. When a URL is followed by a comma, the go
command falls back to later sources only after a 404 (Not Found) or 410 (Gone) response. When a URL is followed by a pipe, the go
command falls back to later sources after any error, including non-HTTP errors such as timeouts. This error handling behavior lets a proxy act as a gatekeeper for unknown modules. For example, a proxy could respond with error 403 (Forbidden) for modules not on an approved list (see Private proxy serving private modules).
The table below specifies queries that a module proxy must respond to. For each path, $base
is the path portion of a proxy URL,$module
is a module path, and $version
is a version. For example, if the proxy URL is https://example.com/mod
, and the client is requesting the go.mod
file for the module golang.org/x/text
at version v0.3.2
, the client would send a GET
request for https://example.com/mod/golang.org/x/text/@v/v0.3.2.mod
.
To avoid ambiguity when serving from case-insensitive file systems, the $module
and $version
elements are case-encoded by replacing every uppercase letter with an exclamation mark followed by the corresponding lower-case letter. This allows modules example.com/M
and example.com/m
to both be stored on disk, since the former is encoded as example.com/!m
.
When resolving the latest version of a module, the go
command will request $base/$module/@v/list
, then, if no suitable versions are found, $base/$module/@latest
. The go
command prefers, in order: the semantically highest release version, the semantically highest pre-release version, and the chronologically most recent pseudo-version. In Go 1.12 and earlier, the go
command considered pseudo-versions in $base/$module/@v/list
to be pre-release versions, but this is no longer true since Go 1.13.
A module proxy must always serve the same content for successful responses for $base/$module/$version.mod
and $base/$module/$version.zip
queries. This content is cryptographically authenticated using go.sum
files and, by default, the checksum database.
The go
command caches most content it downloads from module proxies in its module cache in $GOPATH/pkg/mod/cache/download
. Even when downloading directly from version control systems, the go
command synthesizes explicit info
, mod
, and zip
files and stores them in this directory, the same as if it had downloaded them directly from a proxy. The cache layout is the same as the proxy URL space, so serving $GOPATH/pkg/mod/cache/download
at (or copying it to) https://example.com/proxy
would let users access cached module versions by setting GOPROXY
to https://example.com/proxy
.
The go
command may download module source code and metadata from a module proxy. The GOPROXY
environment variable may be used to configure which proxies the go
command may connect to and whether it may communicate directly with version control systems. Downloaded module data is saved in the module cache. The go
command will only contact a proxy when it needs information not already in the cache.
The GOPROXY
protocol section describes requests that may be sent to a GOPROXY
server. However, it's also helpful to understand when the go
command makes these requests. For example, go build
follows the procedure below:
go.mod
files and performing minimal version selection (MVS).go.mod
, and start over.When the go
command computes the build list, it loads the go.mod
file for each module in the module graph. If a go.mod
file is not in the cache, the go
command will download it from the proxy using a $module/@v/$version.mod
request (where $module
is the module path and $version
is the version). These requests can be tested with a tool like curl
. For example, the command below downloads the go.mod
file for golang.org/x/mod
at version v0.2.0
:
$ curl https://proxy.golang.org/golang.org/x/mod/@v/v0.2.0.mod module golang.org/x/mod go 1.12 require ( golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550 golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898 )
In order to load a package, the go
command needs the source code for the module that provides it. Module source code is distributed in .zip
files which are extracted into the module cache. If a module .zip
is not in the cache, the go
command will download it using a $module/@v/$version.zip
request.
$ curl -O https://proxy.golang.org/golang.org/x/mod/@v/v0.2.0.zip $ unzip -l v0.2.0.zip | head Archive: v0.2.0.zip Length Date Time Name --------- ---------- ----- ---- 1479 00-00-1980 00:00 golang.org/x/mod@v0.2.0/LICENSE 1303 00-00-1980 00:00 golang.org/x/mod@v0.2.0/PATENTS 559 00-00-1980 00:00 golang.org/x/mod@v0.2.0/README 21 00-00-1980 00:00 golang.org/x/mod@v0.2.0/codereview.cfg 214 00-00-1980 00:00 golang.org/x/mod@v0.2.0/go.mod 1476 00-00-1980 00:00 golang.org/x/mod@v0.2.0/go.sum 5224 00-00-1980 00:00 golang.org/x/mod@v0.2.0/gosumcheck/main.go
Note that .mod
and .zip
requests are separate, even though go.mod
files are usually contained within .zip
files. The go
command may need to download go.mod
files for many different modules, and .mod
files are much smaller than .zip
files. Additionally, if a Go project does not have a go.mod
file, the proxy will serve a synthetic go.mod
file that only contains a module
directive. Synthetic go.mod
files are generated by the go
command when downloading from a version control system.
If the go
command needs to load a package not provided by any module in the build list, it will attempt to find a new module that provides it. The section Resolving a package to a module describes this process. In summary, the go
command requests information about the latest version of each module path that could possibly contain the package. For example, for the package golang.org/x/net/html
, the go
command would try to find the latest versions of the modules golang.org/x/net/html
, golang.org/x/net
, golang.org/x/
, and golang.org
. Only golang.org/x/net
actually exists and provides that package, so the go
command uses the latest version of that module. If more than one module provides the package, the go
command will use the module with the longest path.
When the go
command requests the latest version of a module, it first sends a request for $module/@v/list
. If the list is empty or none of the returned versions can be used, it sends a request for $module/@latest
. Once a version is chosen, the go
command sends a $module/@v/$version.info
request for metadata. It may then send $module/@v/$version.mod
and $module/@v/$version.zip
requests to load the go.mod
file and source code.
$ curl https://proxy.golang.org/golang.org/x/mod/@v/list v0.1.0 v0.2.0 $ curl https://proxy.golang.org/golang.org/x/mod/@v/v0.2.0.info {"Version":"v0.2.0","Time":"2020-01-02T17:33:45Z"}
After downloading a .mod
or .zip
file, the go
command computes a cryptographic hash and checks that it matches a hash in the main module's go.sum
file. If the hash is not present in go.sum
, by default, the go
command retrieves it from the checksum database. If the computed hash does not match, the go
command reports a security error and does not install the file in the module cache. The GOPRIVATE
and GONOSUMDB
environment variables may be used to disable requests to the checksum database for specific modules. The GOSUMDB
environment variable may also be set to off
to disable requests to the checksum database entirely. See Authenticating modules for more information. Note that version lists and version metadata returned for .info
requests are not authenticated and may change over time.
The go
command may download module source code and metadata directly from a version control repository. Downloading a module from a proxy is usually faster, but connecting directly to a repository is necessary if a proxy is not available or if a module's repository is not accessible to a proxy (frequently true for private repositories). Git, Subversion, Mercurial, Bazaar, and Fossil are supported. A version control tool must be installed in a directory in PATH
in order for the go
command to use it.
To download specific modules from source repositories instead of a proxy, set the GOPRIVATE
or GONOPROXY
environment variables. To configure the go
command to download all modules directly from source repositories, set GOPROXY
to direct
. See Environment variables for more information.
When the go
command downloads a module in direct
mode, it starts by locating the repository that contains the module. The go
command sends an HTTP GET
request to a URL derived from the module path with a ?go-get=1
query string. For example, for the module golang.org/x/mod
, the go
command may send the following requests:
https://golang.org/x/mod?go-get=1 (preferred) http://golang.org/x/mod?go-get=1 (fallback, only with GOINSECURE)
The go
command will follow redirects but otherwise ignores response status codes, so the server may respond with a 404 or any other error status. The GOINSECURE
environment variable may be set to allow fallback and redirects to unencrypted HTTP for specific modules.
The server must respond with an HTML document containing a <meta>
tag in the document‘s <head>
. The <meta>
tag should appear early in the document to avoid confusing the go
command’s restricted parser. In particular, it should appear before any raw JavaScript or CSS. The <meta>
tag must have the form:
<meta name="go-import" content="root-path vcs repo-url">
root-path
is the repository root path, the portion of the module path that corresponds to the repository‘s root directory. It must be a prefix or an exact match of the requested module path. If it’s not an exact match, another request is made for the prefix to verify the <meta>
tags match.
vcs
is the version control system. It must be one of bzr
, fossil
, git
, hg
, svn
, mod
. The mod
scheme instructs the go
command to download the module from the given URL using the GOPROXY
protocol. This allows developers to distribute modules without exposing source repositories.
repo-url
is the repository's URL. If the URL does not include a scheme, the go
command will try each protocol supported by the version control system. For example, with Git, the go
command will try https://
then git+ssh://
. Insecure protocols may only be used if the module path is matched by the GOINSECURE
environment variable.
As an example, consider golang.org/x/mod
again. The go
command sends a request to https://golang.org/x/mod?go-get=1
. The server responds with an HTML document containing the tag:
<meta name="go-import" content="golang.org/x/mod git https://go.googlesource.com/mod">
From this response, the go
command will use the Git repository at the remote URL https://go.googlesource.com/mod
.
GitHub and other popular hosting services respond to ?go-get=1
queries for all repositories, so usually no server configuration is necessary for modules hosted at those sites.
After the repository URL is found, the go
command will clone the repository into the module cache. In general, the go
command tries to avoid fetching unneeded data from a repository. However, the actual commands used vary by version control system and may change over time. For Git, the go
command can list most available versions without downloading commits. It will usually fetch commits without downloading ancestor commits, but doing so is sometimes necessary.
The go
command may check out a module within a repository at a specific canonical version like v1.2.3
, v2.4.0-beta
, or v3.0.0+incompatible
. Each module version should have a semantic version tag within the repository that indicates which revision should be checked out for a given version.
If a module is defined in the repository root directory or in a major version subdirectory of the root directory, then each version tag name is equal to the corresponding version. For example, the module golang.org/x/text
is defined in the root directory of its repository, so the version v0.3.2
has the tag v0.3.2
in that repository. This is true for most modules.
If a module is defined in a subdirectory within the repository, that is, the module subdirectory portion of the module path is not empty, then each tag name must be prefixed with the module subdirectory, followed by a slash. For example, the module golang.org/x/tools/gopls
is defined in the gopls
subdirectory of the repository with root path golang.org/x/tools
. The version v0.4.0
of that module must have the tag named gopls/v0.4.0
in that repository.
The major version number of a semantic version tag must be consistent with the module path's major version suffix (if any). For example, the tag v1.0.0
could belong to the module example.com/mod
but not example.com/mod/v2
, which would have tags like v2.0.0
.
A tag with major version v2
or higher may belong to a module without a major version suffix if no go.mod
file is present, and the module is in the repository root directory. This kind of version is denoted with the suffix +incompatible
. The version tag itself must not have the suffix. See Compatibility with non-module repositories.
Once a tag is created, it should not be deleted or changed to a different revision. Versions are authenticated to ensure safe, repeatable builds. If a tag is modified, clients may see a security error when downloading it. Even after a tag is deleted, its content may remain available on module proxies.
The go
command may check out a module within a repository at a specific revision, encoded as a pseudo-version like v1.3.2-0.20191109021931-daa7c04131f5
.
The last 12 characters of the pseudo-version (daa7c04131f5
in the example above) indicate a revision in the repository to check out. The meaning of this depends on the version control system. For Git and Mercurial, this is a prefix of a commit hash. For Subversion, this is a zero-padded revision number.
Before checking out a commit, the go
command verifies that the timestamp (20191109021931
above) matches the commit date. It also verifies that the base version (v1.3.1
, the version before v1.3.2
in the example above) corresponds to a semantic version tag that is an ancestor of the commit. These checks ensure that module authors have full control over how pseudo-versions compare with other released versions.
See Pseudo-versions for more information.
A module may be checked out at a specific branch, tag, or revision using a version query.
go get example.com/mod@master
The go
command converts these names into canonical versions that can be used with minimal version selection (MVS). MVS depends on the ability to order versions unambiguously. Branch names and revisions can't be compared reliably over time, since they depend on repository structure which may change.
If a revision is tagged with one or more semantic version tags like v1.2.3
, the tag for the highest valid version will be used. The go
command only considers semantic version tags that could belong to the target module; for example, the tag v1.5.2
would not be considered for example.com/mod/v2
since the major version doesn‘t match the module path’s suffix.
If a revision is not tagged with a valid semantic version tag, the go
command will generate a pseudo-version. If the revision has ancestors with valid semantic version tags, the highest ancestor version will be used as the pseudo-version base. See Pseudo-versions.
Once a module‘s repository has been checked out at a specific revision, the go
command must locate the directory that contains the module’s go.mod
file (the module's root directory).
Recall that a module path consists of three parts: a repository root path (corresponding to the repository root directory), a module subdirectory, and a major version suffix (only for modules released at v2
or higher).
For most modules, the module path is equal to the repository root path, so the module‘s root directory is the repository’s root directory.
Modules are sometimes defined in repository subdirectories. This is typically done for large repositories with multiple components that need to be released and versioned indepently. Such a module is expected to be found in a subdirectory that matches the part of the module's path after the repository root path. For example, suppose the module example.com/monorepo/foo/bar
is in the repository with root path example.com/monorepo
. Its go.mod
file must be in the foo/bar
subdirectory.
If a module is released at major version v2
or higher, its path must have a major version suffix. A module with a major version suffix may be defined in one of two subdirectories: one with the suffix, and one without. For example, suppose a new version of the module above is released with the path example.com/monorepo/foo/bar/v2
. Its go.mod
file may be in either foo/bar
or foo/bar/v2
.
Subdirectories with a major version suffix are major version subdirectories. They may be used to develop multiple major versions of a module on a single branch. This may be unnecessary when development of multiple major versions proceeds on separate branches. However, major version subdirectories have an important property: in GOPATH
mode, package import paths exactly match directories under GOPATH/src
. The go
command provides minimal module compatibility in GOPATH
mode (see Compatibility with non-module repositories), so major version subdirectories aren‘t always necessary for compatibility with projects built in GOPATH
mode. Older tools that don’t support minimal module compatibility may have problems though.
Once the go
command has found the module root directory, it creates a .zip
file of the contents of the directory, then extracts the .zip
file into the module cache. See File path and size constraints) for details on what files may be included in the .zip
file. The contents of the .zip
file are authenticated before extraction into the module cache the same way they would be if the .zip
file were downloaded from a proxy.
Module versions are distributed as .zip
files. There is rarely any need to interact directly with these files, since the go
command creates, downloads, and extracts them automatically from module proxies and version control repositories. However, it's still useful to know about these files to understand cross-platform compatibility constraints or when implementing a module proxy.
The go mod download
command downloads zip files for one or more modules, then extracts those files into the module cache. Depending on GOPROXY
and other environment variables, the go
command may either download zip files from a proxy or clone source control repositories and create zip files from them. The -json
flag may be used to find the location of download zip files and their extracted contents in the module cache.
The golang.org/x/mod/zip
package may be used to create, extract, or check contents of zip files programmatically.
There are a number of restrictions on the content of module zip files. These constraints ensure that zip files can be extracted safely and consistently on a wide range of platforms.
go.mod
files are limited to 16 MiB. LICENSE
files are also limited to 16 MiB. These limits exist to mitigate denial of service attacks on users, proxies, and other parts of the module ecosystem. Repositories that contain more than 500 MiB of files in a module directory tree should tag module versions at commits that only include files needed to build the module's packages; videos, models, and other large assets are usually not needed for builds.$module@$version/
where $module
is the module path and $version
is the version, for example, golang.org/x/mod@v0.3.0/
. The module path must be valid, the version must be valid and canonical, and the version must match the module path's major version suffix. See Module paths and versions for specific definitions and restrictions.go
command does not include empty directories in zip files it creates.strings.EqualFold
). This ensures that zip files can be extracted on case-insensitive file systems without collisions.go.mod
file may or may not appear in the top-level directory ($module@$version/go.mod
). If present, it must have the name go.mod
(all lowercase). Files named go.mod
are not allowed in any other directory.!#$%&()+,-.=@[]^_{}~
. Note that package paths may not contain all these all these characters. See module.CheckFilePath
and module.CheckImportPath
for the differences.CON
, com1
, NuL
, and so on).Go modules are frequently developed and distributed on version control servers and module proxies that aren't available on the public internet. The go
command can download and build modules from private sources, though it usually requires some configuration.
The environment variables below may be used to configure access to private modules. See Environment variables for details. See also Privacy for information on controlling information sent to public servers.
GOPROXY
— list of module proxy URLs. The go
command will attempt to download modules from each server in sequence. The keyword direct
instructs the go
command to download modules from version control repositories where they're developed instead of using a proxy.GOPRIVATE
— list of glob patterns of module path prefixes that should be considered private. Acts as a default value for GONOPROXY
and GONOSUMDB
.GONOPROXY
— list of glob patterns of module path prefixes that should not be downloaded from a proxy. The go
command will download matching modules from version control repositories where they're developed, regardless of GOPROXY
.GONOSUMDB
— list of glob patterns of module path prefixes that should not be checked using the public checksum database, sum.golang.org.GOINSECURE
— list of glob patterns of module path prefixes that may be retrieved over HTTP and other insecure protocols.These variables may be set in the development environment (for example, in a .profile
file), or they may be set permanently with go env -w
.
The rest of this section describes common patterns for providing access to private module proxies and version control repositories.
A central private proxy server that serves all modules (public and private) provides the most control for administrators and requires the least configuration for individual developers.
To configure the go
command to use such a server, set the following environment variables, replacing https://proxy.corp.example.com
with your proxy URL and corp.example.com
with your module prefix:
GOPROXY=https://proxy.corp.example.com GONOSUMDB=corp.example.com
The GOPROXY
setting instructs the go
command to only download modules from https://proxy.corp.example.com
; the go
command will not connect to other proxies or version control repositories.
The GONOSUMDB
setting instructs the go
command not to use the public checksum database to authenticate modules with paths starting with corp.example.com
.
A proxy running in this configuration will likely need read access to private version control servers. It will also need access to the public internet to download new versions of public modules.
There are several existing implementations of GOPROXY
servers that may be used this way. A minimal implementation would serve files from a module cache directory and would use go mod download
(with suitable configuration) to retrieve missing modules.
A private proxy server may serve private modules without also serving publicly available modules. The go
command can be configured to fall back to public sources for modules that aren't available on the private server.
To configure the go
command to work this way, set the following environment variables, replacing https://proxy.corp.example.com
with the proxy URL and corp.example.com
with the module prefix:
GOPROXY=https://proxy.corp.example.com,https://proxy.golang.org,direct GONOSUMDB=corp.example.com
The GOPROXY
setting instructs the go
command to try to download modules from https://proxy.corp.example.com
first. If that server responds with 404 (Not Found) or 410 (Gone), the go
command will fall back to https://proxy.golang.org
, then to direct connections to repositories.
The GONOSUMDB
setting instructs the go
command not to use the public checksum database to authenticate modules whose paths start with corp.example.com
.
Note that a proxy used in this configuration may still control access to public modules, even though it doesn't serve them. If the proxy responds to a request with an error status other than 404 or 410, the go
command will not fall back to later entries in the GOPROXY
list. For example, the proxy could respond with 403 (Forbidden) for a module with an unsuitable license or with known security vulnerabilities.
The go
command may be configured to bypass public proxies and download private modules directly from version control servers. This is useful when running a private proxy server is not feasible.
To configure the go
command to work this way, set GOPRIVATE
, replacing corp.example.com
the private module prefix:
GOPRIVATE=corp.example.com
The GOPROXY
variable does not need to be changed in this situation. It defaults to https://proxy.golang.org,direct
, which instructs the go
command to attempt to download modules from https://proxy.golang.org
first, then fall back to a direct connection if that proxy responds with 404 (Not Found) or 410 (Gone).
The GOPRIVATE
setting instructs the go
command not to connect to a proxy or to the checksum database for modules starting with corp.example.com
.
An internal HTTP server may still be needed to resolve module paths to repository URLs. For example, when the go
command downloads the module corp.example.com/mod
, it will send a GET request to https://corp.example.com/mod?go-get=1
, and it will look for the repository URL in the response. To avoid this requirement, ensure that each private module path has a VCS suffix (like .git
) marking the repository root prefix. For example, when the go
command downloads the module corp.example.com/repo.git/mod
, it will clone the Git repository at https://corp.example.com/repo.git
or ssh://corp.example.com/repo.git
without needing to make additional requests.
Developers will need read access to repositories containing private modules. This may be configured in global VCS configuration files like .gitconfig
. It's best if VCS tools are configured not to need interactive authentication prompts. By default, when invoking Git, the go
command disables interactive prompts by setting GIT_TERMINAL_PROMPT=0
, but it respects explicit settings.
The go
command supports HTTP basic authentication when communicating with proxy servers.
Credentials may be specified in a .netrc
file. For example, a .netrc
file containing the lines below would configure the go
command to connect to the machine proxy.corp.example.com
with the given username and password.
machine proxy.corp.example.com login jrgopher password hunter2
The location of the file may be set with the NETRC
environment variable. If NETRC
is not set, the go
command will read $HOME/.netrc
on UNIX-like platforms or %USERPROFILE%\_netrc
on Windows.
Fields in .netrc
are separated with spaces, tabs, and newlines. Unfortunately, these characters cannot be used in usernames or passwords. Note also that the machine name cannot be a full URL, so it's not possible to specify different usernames and passwords for different paths on the same machine.
Alternatively, credentials may be specified directly in GOPROXY
URLs. For example:
GOPROXY=https://jrgopher:hunter2@proxy.corp.example.com
Use caution when taking this approach: environment variables may be appear in shell history and in logs.
The go
command may download modules and metadata from module proxy servers and version control systems. The environment variable GOPROXY
controls which servers are used. The environment variables GOPRIVATE
and GONOPROXY
control which modules are fetched from proxies.
The default value of GOPROXY
is:
https://proxy.golang.org,direct
With this setting, when the go
command downloads a module or module metadata, it will first send a request to proxy.golang.org
, a public module proxy operated by Google (privacy policy). See GOPROXY
protocol for details on what information is sent in each request. The go
command does not transmit personally identifiable information, but it does transmit the full module path being requested. If the proxy responds with a 404 (Not Found) or 410 (Gone) status, the go
command will attempt to connect directly to the version control system providing the module. See Version control systems for details.
The GOPRIVATE
or GONOPROXY
environment variables may be set to lists of glob patterns matching module prefixes that are private and should not be requested from any proxy. For example:
GOPRIVATE=*.corp.example.com,*.research.example.com
GOPRIVATE
simply acts as a default for GONOPROXY
and GONOSUMDB
, so it's not necessary to set GONOPROXY
unless GONOSUMDB
should have a different value. When a module path is matched by GONOPROXY
, the go
command ignores GOPROXY
for that module and fetches it directly from its version control repository. This is useful when no proxy serves private modules. See Direct access to private modules.
If there is a trusted proxy serving all modules, then GONOPROXY
should not be set. For example, if GOPROXY
is set to one source, the go
command will not download modules from other sources. GONOSUMDB
should still be set in this situation.
GOPROXY=https://proxy.corp.example.com GONOSUMDB=*.corp.example.com,*.research.example.com
If there is a trusted proxy serving only private modules, GONOPROXY
should not be set, but care must be taken to ensure the proxy responds with the correct status codes. For example, consider the following configuration:
GOPROXY=https://proxy.corp.example.com,https://proxy.golang.org GONOSUMDB=*.corp.example.com,*.research.example.com
Suppose that due to a typo, a developer attempts to download a module that doesn't exist.
go mod download corp.example.com/secret-product/typo@latest
The go
command first requests this module from proxy.corp.example.com
. If that proxy responds with 404 (Not Found) or 410 (Gone), the go
command will fall back to proxy.golang.org
, transmitting the secret-product
path in the request URL. If the private proxy responds with any other error code, the go
command prints the error and will not fall back to other sources.
In addition to proxies, the go
command may connect to the checksum database to verify cryptographic hashes of modules not listed in go.sum
. The GOSUMDB
environment variable sets the name, URL, and public key of the checksum database. The default value of GOSUMDB
is sum.golang.org
, the public checksum database operated by Google (privacy policy). See Checksum database for details on what is transmitted with each request. As with proxies, the go
command does not transmit personally identifiable information, but it does transmit the full module path being requested, and the checksum database cannot compute checksums for non-public modules.
The GONOSUMDB
environment variable may be set to patterns indicating which modules are private and should not be requested from the checksum database. GOPRIVATE
acts as a default for GONOSUMDB
and GONOPROXY
, so it's not necessary to set GONOSUMDB
unless GONOPROXY
should have a different value.
A proxy may mirror the checksum database. If a proxy in GOPROXY
does this, the go
command will not connect to the checksum database directly.
GOSUMDB
may be set to off
to disable use of the checksum database entirely. With this setting, the go
command will not authenticate downloaded modules unless they're already in go.sum
. See Authenticating modules.
The module cache is the directory where the go
command stores downloaded module files. The module cache is distinct from the build cache, which contains compiled packages and other build artifacts.
The default location of the module cache is $GOPATH/pkg/mod
. To use a different location, set the GOMODCACHE
environment variable.
The module cache has no maximum size, and the go
command does not remove its contents automatically.
The cache may be shared by multiple Go projects developed on the same machine. The go
command will use the same cache regardless of the location of the main module. Multiple instances of the go
command may safely access the same module cache at the same time.
The go
command creates module source files and directories in the cache with read-only permissions to prevent accidental changes to modules after they're downloaded. This has the unfortunate side-effect of making the cache difficult to delete with commands like rm -rf
. The cache may instead be deleted with go clean -modcache
. Alternatively, when the -modcacherw
flag is used, the go
command will create new directories with read-write permissions. This increases the risk of editors, tests, and other programs modifying files in the module cache. The go mod verify
command may be used to detect modifications to dependencies of the main module. It scans the extracted contents of each module dependency and confirms they match the expected hash in go.sum
.
The table below explains the purpose of most files in the module cache. Some transient files (lock files, temporary directories) are omitted. For each path, $module
is a module path, and $version
is a version. Paths ending with slashes (/
) are directories. Capital letters in module paths and versions are escaped using exclamation points (Azure
is escaped as !azure
) to avoid conflicts on case-insensitive file systems.
When the go
command downloads a module zip file or go.mod
file into the module cache, it computes a cryptographic hash and compares it with a known value to verify the file hasn't changed since it was first downloaded. The go
command reports a security error if a downloaded file does not have the correct hash.
For go.mod
files, the go
commmand computes the hash from the file content. For module zip files, the go
command computes the hash from the names and contents of files within the archive in a deterministic order. The hash is not affected by file order, compression, alignment, and other metadata. See golang.org/x/mod/sumdb/dirhash
for hash implementation details.
The go
command compares each hash with the corresponding line in the main module's go.sum
file. If the hash is different from the hash in go.sum
, the go
command reports a security error and deletes the downloaded file without adding it into the module cache.
If the go.sum
file is not present, or if it doesn't contain a hash for the downloaded file, the go
command may verify the hash using the checksum database, a global source of hashes for publicly available modules. Once the hash is verified, the go
command adds it to go.sum
and adds the downloaded file in the module cache. If a module is private (matched by the GOPRIVATE
or GONOSUMDB
environment variables) or if the checksum database is disabled (by setting GOSUMDB=off
), the go
command accepts the hash and adds the file to the module cache without verifying it.
The module cache is usually shared by all Go projects on a system, and each module may have its own go.sum
file with potentially different hashes. To avoid the need to trust other modules, the go
command verifies hashes using the main module's go.sum
whenever it accesses a file in the module cache. Zip file hashes are expensive to compute, so the go
command checks pre-computed hashes stored alongside zip files instead of re-hashing the files. The go mod verify
command may be used to check that zip files and extracted directories have not been modified since they were added to the module cache.
A module may have a text file named go.sum
in its root directory, alongside its go.mod
file. The go.sum
file contains cryptographic hashes of the module‘s direct and indirect dependencies. When the go
command downloads a module .mod
or .zip
file into the module cache, it computes a hash and checks that the hash matches the corresponding hash in the main module’s go.sum
file. go.sum
may be empty or absent if the module has no dependencies or if all dependencies are replaced with local directories using replace
directives.
Each line in go.sum
has three fields separated by spaces: a module path, a version (possibly ending with /go.mod
), and a hash.
/go.mod
, the hash is for the module‘s go.mod
file only; otherwise, the hash is for the files within the module’s .zip
file.h1
) and a base64-encoded cryptographic hash, separated by a colon (:
). Currently, SHA-256 (h1
) is the only supported hash algorithm. If a vulnerability in SHA-256 is discovered in the future, support will be added for another algorithm (named h2
and so on).The go.sum
file may contain hashes for multiple versions of a module. The go
command may need to load go.mod
files from multiple versions of a dependency in order to perform minimal version selection. go.sum
may also contain hashes for module versions that aren't needed anymore (for example, after an upgrade). go mod tidy
will add missing hashes and will remove unnecessary hashes from go.sum
.
The checksum database is a global source of go.sum
lines. The go
command can use this in many situations to detect misbehavior by proxies or origin servers.
The checksum database allows for global consistency and reliability for all publicly available module versions. It makes untrusted proxies possible since they can‘t serve the wrong code without it going unnoticed. It also ensures that the bits associated with a specific version do not change from one day to the next, even if the module’s author subsequently alters the tags in their repository.
The checksum database is served by sum.golang.org, which is run by Google. It is a Transparent Log (or “Merkle Tree”) of go.sum
line hashes, which is backed by Trillian. The main advantage of a Merkle tree is that independent auditors can verify that it hasn't been tampered with, so it is more trustworthy than a simple database.
The go
command interacts with the checksum database using the protocol originally outlined in Proposal: Secure the Public Go Module Ecosystem.
The table below specifies queries that the checksum database must respond to. For each path, $base
is the path portion of the checksum database URL, $module
is a module path, and $version
is a version. For example, if the checksum database URL is https://sum.golang.org
, and the client is requesting the record for the module golang.org/x/text
at version v0.3.2
, the client would send a GET
request for https://sum.golang.org/lookup/golang.org/x/text@v0.3.2
.
To avoid ambiguity when serving from case-insensitive file systems, the $module
and $version
elements are case-encoded by replacing every uppercase letter with an exclamation mark followed by the corresponding lower-case letter. This allows modules example.com/M
and example.com/m
to both be stored on disk, since the former is encoded as example.com/!m
.
Parts of the path surrounded by square brakets, like [.p/$W]
denote optional values.
If the go
command consults the checksum database, then the first step is to retrieve the record data through the /lookup
endpoint. If the module version is not yet recorded in the log, the checksum database will try to fetch it from the origin server before replying. This /lookup
data provides the sum for this module version as well as its position in the log, which informs the client of which tiles should be fetched to perform proofs. The go
command performs “inclusion” proofs (that a specific record exists in the log) and “consistency” proofs (that the tree hasn’t been tampered with) before adding new go.sum
lines to the main module’s go.sum
file. It‘s important that the data from /lookup
should never be used without first authenticating it against the signed tree hash and authenticating the signed tree hash against the client’s timeline of signed tree hashes.
Signed tree hashes and new tiles served by the checksum database are stored in the module cache, so the go
command only needs to fetch tiles that are missing.
The go
command doesn't need to directly connect to the checksum database. It can request module sums via a module proxy that mirrors the checksum database and supports the protocol above. This can be particularly helpful for private, corporate proxies which block requests outside the organization.
The GOSUMDB
environment variable identifies the name of checksum database to use and optionally its public key and URL, as in:
GOSUMDB="sum.golang.org" GOSUMDB="sum.golang.org+<publickey>" GOSUMDB="sum.golang.org+<publickey> https://sum.golang.org"
The go
command knows the public key of sum.golang.org
, and also that the name sum.golang.google.cn
(available inside mainland China) connects to the sum.golang.org
checksum database; use of any other database requires giving the public key explicitly. The URL defaults to https://
followed by the database name.
GOSUMDB
defaults to sum.golang.org
, the Go checksum database run by Google. See https://sum.golang.org/privacy for the service's privacy policy.
If GOSUMDB
is set to off
, or if go get
is invoked with the -insecure
flag, the checksum database is not consulted, and all unrecognized modules are accepted, at the cost of giving up the security guarantee of verified repeatable downloads for all modules. A better way to bypass the checksum database for specific modules is to use the GOPRIVATE
or GONOSUMDB
environment variables. See Private Modules for details.
The go env -w
command can be used to set these variables for future go
command invocations.
Module behavior in the go
command may be configured using the environment variables listed below. This list only includes module-related environment variables. See go help environment
for a list of all environment variables recognized by the go
command.
build constraint: A condition that determines whether a Go source file is used when compiling a package. Build constraints may be expressed with file name suffixes (for example, foo_linux_amd64.go
) or with build constraint comments (for example, // +build linux,amd64
). See Build Constraints.
build list: The list of module versions that will be used for a build command such as go build
, go list
, or go test
. The build list is determined from the main module's go.mod
file and go.mod
files in transitively required modules using minimal version selection. The build list contains versions for all modules in the module graph, not just those relevant to a specific command.
canonical version: A correctly formatted version without a build metadata suffix other than +incompatible
. For example, v1.2.3
is a canonical version, but v1.2.3+meta
is not.
go.mod
file: The file that defines a module's path, requirements, and other metadata. Appears in the module's root directory. See the section on go.mod
files.
import path: A string used to import a package in a Go source file. Synonymous with package path.
main module: The module in which the go
command is invoked.
major version: The first number in a semantic version (1
in v1.2.3
). In a release with incompatible changes, the major version must be incremented, and the minor and patch versions must be set to 0. Semantic versions with major version 0 are considered unstable.
major version subdirectory: A subdirectory within a version control repository matching a module's major version suffix where a module may be defined. For example, the module example.com/mod/v2
in the repository with root path example.com/mod
may be defined in the repository root directory or the major version subdirectory v2
. See Module directories within a repository.
major version suffix: A module path suffix that matches the major version number. For example, /v2
in example.com/mod/v2
. Major version suffixes are required at v2.0.0
and later and are not allowed at earlier versions. See the section on Major version suffixes.
minimal version selection (MVS): The algorithm used to determine the versions of all modules that will be used in a build. See the section on Minimal version selection for details.
minor version: The second number in a semantic version (2
in v1.2.3
). In a release with new, backwards compatible functionality, the minor version must be incremented, and the patch version must be set to 0.
module: A collection of packages that are released, versioned, and distributed together.
module cache: A local directory storing downloaded modules, located in GOPATH/pkg/mod
. See Module cache.
module graph: The directed graph of module requirements, rooted at the main module. Each vertex in the graph is a module; each edge is a version from a require
statement in a go.mod
file (subject to replace
and exclude
statements in the main module's go.mod
file.
module path: A path that identifies a module and acts as a prefix for package import paths within the module. For example, "golang.org/x/net"
.
module proxy: A web server that implements the GOPROXY
protocol. The go
command downloads version information, go.mod
files, and module zip files from module proxies.
module root directory: The directory that contains the go.mod
file that defines a module.
module subdirectory: The portion of a module path after the repository root path that indicates the subdirectory where the module is defined. When non-empty, the module subdirectory is also a prefix for semantic version tags. The module subdirectory does not include the major version suffix, if there is one, even if the module is in a major version subdirectory. See Module paths.
package: A collection of source files in the same directory that are compiled together. See the Packages section in the Go Language Specification.
package path: The path that uniquely identifies a package. A package path is a module path joined with a subdirectory within the module. For example "golang.org/x/net/html"
is the package path for the package in the module "golang.org/x/net"
in the "html"
subdirectory. Synonym of import path.
patch version: The third number in a semantic version (3
in v1.2.3
). In a release with no changes to the module's public interface, the patch version must be incremented.
pre-release version: A version with a dash followed by a series of dot-separated identifiers immediately following the patch version, for example, v1.2.3-beta4
. Pre-release versions are considered unstable and are not assumed to be compatible with other versions. A pre-release version sorts before the corresponding release version: v1.2.3-pre
comes before v1.2.3
. See also release version.
pseudo-version: A version that encodes a revision identifier (such as a Git commit hash) and a timestamp from a version control system. For example, v0.0.0-20191109021931-daa7c04131f5
. Used for compatibility with non-module repositories and in other situations when a tagged version is not available.
release version: A version without a pre-release suffix. For example, v1.2.3
, not v1.2.3-pre
. See also pre-release version.
repository root path: The portion of a module path that corresponds to a version control repository's root directory. See Module paths.
semantic version tag: A tag in a version control repository that maps a version to a specific revision. See Mapping versions to commits.
vendor directory: A directory named vendor
that contains packages from other modules needed to build packages in the main module. Maintained with go mod vendor
. See Vendoring.
version: An identifier for an immutable snapshot of a module, written as the letter v
followed by a semantic version. See the section on Versions.