Black Lives Matter. Support the Equal Justice Initiative.

go.mod file reference

Each Go module is defined by a go.mod file that describes the module's properties, including its dependencies on other modules and on versions of Go.

These properties include:

Go generates a go.mod file when you run the go mod init command. The following example creates a go.mod file, setting the module's module path to example.com/mymodule:

$ go mod init example.com/mymodule

Use go commands to manage dependencies. The commands ensure that the requirements described in your go.mod file remain consistent and the content of your go.mod file is valid. These commands include the go get and go mod tidy and go mod edit commands.

For reference on go commands, see Command go. You can get help from the command line by typing go help command-name, as with go help mod tidy.

See also

Example

A go.mod file includes directives shown in the following example. These are described in this topic.

module example.com/mymodule

go 1.14

require (
    example.com/othermodule v1.2.3
    example.com/thismodule v1.2.3
    example.com/thatmodule v1.2.3
)

replace example.com/thatmodule => ../thatmodule
exclude example.com/thismodule v1.3.0

module

Declares the module's module path, which is the module's unique identifier (when combined with the module version number). This becomes the import prefix for all packages the module contains.

Syntax

module module-path
module-path
The module's module path, usually the repository location from which the module can be downloaded by Go tools. For module versions v2 and later, this value must end with the major version number, such as /v2.

Examples

The following examples substitute example.com for a repository domain from which the module could be downloaded.

Notes

The module path should be a path from which Go tools can download the module source. In practice, this is typically the module source's repository domain and path to the module code within the repository. The go command relies on this form when downloading module versions to resolve dependencies on the module user's behalf.

Even if you're not at first intending to make your module available for use from other code, using its repository path is a best practice that will help you avoid having to rename the module if you publish it later.

If at first you don't know the module's eventual repository location, consider temporarily using a safe substitute, such as the name of a domain you own or example.com, along with a path following from the module's name or source directory.

For example, if you're developing in a stringtools directory, your temporary module path might be example.com/stringtools, as in the following example:

go mod init example.com/stringtools

go

Indicates that the module was written assuming the semantics of the Go version specified by the directive.

Syntax

go minimum-go-version
minimum-go-version
The minimum version of Go required to compile packages in this module.

Examples

Notes

The go directive was originally intended to support backward incompatible changes to the Go language (see Go 2 transition). There have been no incompatible language changes since modules were introduced, but the go directive still affects use of new language features:

Additionally, the go command changes its behavior based on the version specified by the go directive. This has the following effects:

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.

require

Declares a module as dependency required by the current module, specifying the minimum version of the module required.

Syntax

require module-path module-version
module-path
The module's module path, usually a concatenation of the module source's repository domain and the module name. For module versions v2 and later, this value must end with the major version number, such as /v2.
module-version
The module's version. This can be either a release version number, such as v1.2.3, or a Go-generated pseudo-version number, such as v0.0.0-20200921210052-fa0125251cc4.

Examples

Notes

When you run a go command such as go get, Go inserts require directives for each module containing imported packages. When a module isn't yet tagged in its repository, Go assigns a pseudo-version number it generates when you run the command.

You can have Go require a module from a location other than its repository by using the replace directive.

For more about version numbers, see Module version numbering.

For more about managing dependencies, see the following:

replace

Replaces the content of a module at a specific version (or all versions) with another module version or with a local directory. Go tools will use the replacement path when resolving the dependency.

Syntax

replace module-path [module-version] => replacement-path [replacement-version]
module-path
The module path of the module to replace.
module-version
Optional. A specific version to replace. If this version number is omitted, all versions of the module are replaced with the content on the right side of the arrow.
replacement-path
The path at which Go should look for the required module. This can be a module path or a path to a directory on the file system local to the replacement module. If this is a module path, you must specify a replacement-version value. If this is a local path, you may not use a replacement-version value.
replacement-version
The version of the replacement module. The replacement version may only be specified if replacement-path is a module path (not a local directory).

Examples

Notes

Use the replace directive to temporarily substitute a module path value with another value when you want Go to use the other path to find the module's source. This has the effect of redirecting Go's search for the module to the replacement's location. You needn't change package import paths to use the replacement path.

Use the exclude and replace directives to control build-time dependency resolution when building the current module. These directives are ignored in modules that depend on the current module.

The replace directive can be useful in situations such as the following:

Note that a replace directive alone does not does not add a module to the module graph. A require directive that refers to a replaced module version is also needed, either in the main module's go.mod file or a dependency's go.mod file. If you don't have a specific version to replace, you can use a fake version, as in the example below. Note that this will break modules that depend on your module, since replace directives are only applied in the main module.

require example.com/mod v0.0.0-replace

replace example.com/mod v0.0.0-replace => ./mod

For more on replacing a required module, including using Go tools to make the change, see:

For more about version numbers, see Module version numbering.

exclude

Specifies a module or module version to exclude from the current module's dependency graph.

Syntax

exclude module-path module-version
module-path
The module path of the module to exclude.
module-version
The specific version to exclude.

Example

Notes

Use the exclude directive to exclude a specific version of a module that is indirectly required but can't be loaded for some reason. For example, you might use it to exclude a version of a module that has an invalid checksum.

Use the exclude and replace directives to control build-time dependency resolution when building the current module (the main module you're building). These directives are ignored in modules that depend on the current module.

You can use the go mod edit command to exclude a module, as in the following example.

go mod edit -exclude=example.com/theirmodule@v1.3.0

For more about version numbers, see Module version numbering.