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/mymodule:
$ go mod init example/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
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
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.
For more, see module directive in the Go Modules Reference.
The following examples substitute example.com for a repository domain from which the module could be downloaded.
module example.com/mymodule
module example.com/mymodule/v2
The module path must uniquely identify your module. For most modules, the path is a URL where the go command can find the code (or a redirect to the code). For modules that won't ever be downloaded directly, the module path can be just some name you control that will ensure uniqueness. The prefix example/ is also reserved for use in examples like these.
For more details, see Managing dependencies.
In practice, the module path 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 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.
For example, if you‘re developing in a stringtools directory, your temporary module path might be <company-name>/stringtools, as in the following example, where company-name is your company’s name:
go mod init <company-name>/stringtools
Indicates that the module was written assuming the semantics of the Go version specified by the directive.
For more, see go directive in the Go Modules Reference.
go 1.14
The go directive sets the minimum version of Go required to use this module. Before Go 1.21, the directive was advisory only; now it is a mandatory requirement: Go toolchains refuse to use modules declaring newer Go versions.
The go directive is an input into selecting which Go toolchain to run. See “Go toolchains” for details.
The go directive affects use of new language features:
go directive. For example, if a module has the directive go 1.12, its packages may not use numeric literals like 1_000_000, which were introduced in Go 1.13.go 1.13 and a package uses the numeric literal 1_000_000. If that package is built with Go 1.12, the compiler notes that the code is written for Go 1.13.The go directive also affects the behavior of the go command:
go 1.14 or higher, automatic vendoring may be enabled. If the file vendor/modules.txt is present and consistent with go.mod, there is no need to explicitly use the -mod=vendor flag.go 1.16 or higher, the all package pattern matches only packages transitively imported by packages and tests in the main module. This is the same set of packages retained by go mod vendor since modules were introduced. In lower versions, all also includes tests of packages imported by packages in the main module, tests of those packages, and so on.go 1.17 or higher:go.mod file includes an explicit require directive for each module that provides any package transitively imported by a package or test in the main module. (At go 1.16 and lower, an indirect dependency is included only if minimal version selection would otherwise select a different version.) This extra information enables module graph pruning and lazy module loading.// indirect dependencies than in previous go versions, indirect dependencies are recorded in a separate block within the go.mod file.go mod vendor omits go.mod and go.sum files for vendored dependencies. (That allows invocations of the go command within subdirectories of vendor to identify the correct main module.)go mod vendor records the go version from each dependency's go.mod file in vendor/modules.txt.go 1.21 or higher:go line declares a required minimum version of Go to use with this module.go line must be greater than or equal to the go line of all dependencies.go command no longer attempts to maintain compatibility with the previous older version of Go.go command is more careful about keeping checksums of go.mod files in the go.sum file.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.
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.
For more see “Go toolchains” and toolchain directive in the Go Modules Reference.
toolchain go1.21.0
See “Go toolchains” for details about how the toolchain line affects Go toolchain selection.
Declares a module as a dependency of the current module, specifying the minimum version of the module required.
For more, see require directive in the Go Modules Reference.
require example.com/othermodule v1.2.3
require example.com/othermodule v0.0.0-20200921210052-fa0125251cc4
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:
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.
For more, see replace directive in the Go Modules Reference.
Replacing with a fork of the module repository
In the following example, any version of example.com/othermodule is replaced with the specified fork of its code.
require example.com/othermodule v1.2.3 replace example.com/othermodule => example.com/myfork/othermodule v1.2.3-fixed
When you replace one module path with another, do not change import statements for packages in the module you're replacing.
For more on using a forked copy of module code, see Requiring external module code from your own repository fork.
Replacing with a different version number
The following example specifies that version v1.2.3 should be used instead of any other version of the module.
require example.com/othermodule v1.2.2 replace example.com/othermodule => example.com/othermodule v1.2.3
The following example replaces module version v1.2.5 with version v1.2.3 of the same module.
replace example.com/othermodule v1.2.5 => example.com/othermodule v1.2.3
Replacing with local code
The following example specifies that a local directory should be used as a replacement for all versions of the module.
require example.com/othermodule v1.2.3 replace example.com/othermodule => ../othermodule
The following example specifies that a local directory should be used as a replacement for v1.2.5 only.
require example.com/othermodule v1.2.5 replace example.com/othermodule v1.2.5 => ../othermodule
For more on using a local copy of module code, see Requiring module code in a local directory.
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 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.
Specifies a module or module version to exclude from the current module's dependency graph.
For more, see exclude directive in the Go Modules Reference.
Exclude example.com/theirmodule version v1.3.0
exclude example.com/theirmodule v1.3.0
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.
Indicates that a version or range of versions of the module defined by go.mod should not be depended upon. A retract directive is useful when a version was published prematurely or a severe problem was discovered after the version was published.
For more, see retract directive in the Go Modules Reference.
Retracting a single version
retract v1.1.0 // Published accidentally.
Retracting a range of versions
retract [v1.0.0,v1.0.5] // Build broken on some platforms.
Use the retract directive to indicate that a previous version of your module should not be used. Users will not automatically upgrade to a retracted version with go get, go mod tidy, or other commands. Users will not see a retracted version as an available update with go list -m -u.
Retracted versions should remain available so users that already depend on them are able to build their packages. Even if a retracted version is deleted from the source repository, it may remain available on mirrors such as proxy.golang.org. Users that depend on retracted versions may be notified when they run go get or go list -m -u on related modules.
The go command discovers retracted versions by reading retract directives in the go.mod file in the latest version of a module. The latest version is, in order of precedence:
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.
For example, if you accidentally tag v1.0.0, you can tag v1.0.1 with the following directives:
retract v1.0.0 // Published accidentally. retract v1.0.1 // Contains retraction only.
Unfortunately, once a version is published, it cannot be changed. If you later tag v1.0.0 at a different commit, the go command may detect a mismatched sum in go.sum or in the checksum database.
Retracted versions of a module do not normally appear in the output of go list -m -versions, but you can use the -retracted to show them. For more, see go list -m in the Go Modules Reference.