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, to exclude a specific version of a required module, or to ignore specific directories within the module when matching package patterns.

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

Go tools make changes to your go.mod file as you use them to manage dependencies. For more, see Managing dependencies.
For more details and constraints related to go.mod files, see the Go modules reference.

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.

For more, see module directive in the Go Modules Reference.

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.

Module declaration for a v0 or v1 module:
```
module example.com/mymodule
```
Module path for a v2 module:
```
module example.com/mymodule/v2
```

Notes

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

go

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.

Syntax

go minimum-go-version

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

Examples

Module must run on Go version 1.14 or later:
```
go 1.14
```

Notes

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:

For packages within the module, the compiler rejects use of language features introduced after the version specified by the 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.
If an older Go version builds one of the module’s packages and encounters a compile error, the error notes that the module was written for a newer Go version. For example, suppose a module has 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:

At 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.
At 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.
At go 1.17 or higher:
- The 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.
- Because there may be many more // 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.
At go 1.21 or higher:
- The go line declares a required minimum version of Go to use with this module.
- The go line must be greater than or equal to the go line of all dependencies.
- The go command no longer attempts to maintain compatibility with the previous older version of Go.
- The 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.

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.

For more see “Go toolchains” and toolchain directive in the Go Modules Reference.

Syntax

toolchain toolchain-name

toolchain-name: The suggested Go toolchain's name. Standard toolchain names take the form goV for a Go version V, as in go1.21.0 and go1.18rc1. The special value default disables automatic toolchain switching.

Examples

Suggest using Go 1.21.0 or newer:
```
toolchain go1.21.0
```

Notes

See “Go toolchains” for details about how the toolchain line affects Go toolchain selection.

godebug

Indicates the default GODEBUG settings to be applied to the main packages of this module. These override any toolchain defaults, and are overridden by explicit //go:debug lines in main packages.

Syntax

godebug debug-key=debug-value

debug-key: The name of the setting to be applied. A list of settings and the versions they were introduced in can be found at GODEBUG History.
debug-value: The value provided to the setting. If not otherwise specified, 0 to disable and 1 to enable the named behavior.

Examples

Use the new 1.23 asynctimerchan=0 behavior:
```
godebug asynctimerchan=0
```
Use the default GODEBUGs from Go 1.21, but the old panicnil=1 behavior:
```
godebug (
    default=go1.21
    panicnil=1
)
```

Notes

GODEBUG settings only apply for builds of main packages and test binaries in the current module. They have no effect when a module is used as a dependency.

See “Go, Backwards Compatibility, and GODEBUG” for details on backwards compatibility.