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:

The current module’s module path. This should be a location from which the module can be downloaded by Go tools, such as the module code’s repository location. This serves as a unique identifier, when combined with the module’s version number. It is also the prefix of the package path for all packages in the module. For more about how Go locates the module, see the Go Modules Reference.
The minimum version of Go required by the current module.
A list of minimum versions of other modules required by the current module.
Instructions, optionally, to replace a required module with another module version or a local directory, or to exclude a specific version of a required module.

go mod init

$ go mod init example/mymodule

gogo getgo mod tidygo mod edit

gogo helpgo help mod tidy

See also

Example

A go.mod file includes directives as shown in the following example. These are described elsewhere 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). The module path becomes the import prefix for all packages the module contains.

module

Syntax

module module-path

/v2

Examples

example.com

module example.com/mymodule

module example.com/mymodule/v2

Notes

goexample/

For more details, see Managing dependencies.

go

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 a name you control (such as your company name), along with a path following from the module’s name or source directory. For more, see Managing dependencies.

stringtools/stringtools

go mod init <company-name>/stringtools

go

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

go

Syntax

go minimum-go-version

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

Examples

go 1.14

Notes

go

go

go

gogo 1.121_000_000go 1.131_000_000

gogo

go 1.14vendor/modules.txtgo.mod-mod=vendorgo 1.16allgo mod vendorallgo 1.17go 1.21gogogogogogo.modgo.sum

go.modgogo

toolchain

Declares a suggested Go toolchain to use with this module. Only takes effect when the module is the main module and the default toolchain is older than the suggested toolchain.

toolchain

Syntax

toolchain toolchain-name

goVgo1.21.0go1.18rc1default

Examples

toolchain go1.21.0

Notes

toolchain

require

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

require

Syntax

require module-path module-version

/v2

Examples

require example.com/othermodule v1.2.3

require example.com/othermodule v0.0.0-20200921210052-fa0125251cc4

Notes

gogo getrequire

replace

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.

replace

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

require example.com/othermodule v1.2.3

replace example.com/othermodule => example.com/myfork/othermodule v1.2.3-fixed

require example.com/othermodule v1.2.2

replace example.com/othermodule => example.com/othermodule v1.2.3

replace example.com/othermodule v1.2.5 => example.com/othermodule v1.2.3

require example.com/othermodule v1.2.3

replace example.com/othermodule => ../othermodule

require example.com/othermodule v1.2.5

replace example.com/othermodule v1.2.5 => ../othermodule

Notes

replace

excludereplace

replace

You’re developing a new module whose code is not yet in the repository. You want to test with clients using a local version.
You’ve identified an issue with a dependency, have cloned the dependency’s repository, and you’re testing a fix with the local repository.

replacerequirego.modgo.modreplace

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.

exclude

Syntax

exclude module-path module-version

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

Example

exclude example.com/theirmodule v1.3.0

Notes

exclude

excludereplace

go mod edit

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

For more about version numbers, see Module version numbering.

retract

go.modretract

retract

Syntax

retract version // rationale
retract [version-low,version-high] // rationale

version: A single version to retract.
version-low: Lower bound of a range of versions to retract.
version-high: Upper bound of a range of versions to retract. Both version-low and version-high are included in the range.
rationale: Optional comment explaining the retraction. May be shown in messages to the user.

Example

retract v1.1.0 // Published accidentally.

retract [v1.0.0,v1.0.5] // Build broken on some platforms.

Notes

retractgo getgo mod tidygo list -m -u

go getgo list -m -u

goretractgo.mod

Its highest release version, if any
Its highest pre-release version, if any
A pseudo-version for the tip of the repository’s default branch.

When you add a retraction, you almost always need to tag a new, higher version so the command will see it in the latest version of the module.

You can publish a version whose sole purpose is to signal retractions. In this case, the new version may also retract itself.

v1.0.0v1.0.1

retract v1.0.0 // Published accidentally.
retract v1.0.1 // Contains retraction only.

v1.0.0gogo.sum

go list -m -versions-retractedgo list -m