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
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
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.
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 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
Specifies the minimum Go version required by the module.
go 1.14
The version number also controls some module-related features in the go
command. For example, if the vendor directory is present, that directory will be used automatically if the version number is 1.14 or higher.
For more about version numbers, see Module version numbering.
Declares a module as dependency required by the current module, specifying the minimum version of the module required.
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.
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:
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.
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.