Go Reference ยท The go Command and Tools
The go mod command
Reference for go mod: init, tidy, download, vendor, verify, why, graph and edit, plus the go.mod and go.sum files, directives and common workflows.
go mod maintains modules, the unit of versioning and dependency management in Go. A module is a tree of packages with a go.mod file at its root that records the module path, the minimum Go version, and every dependency with the minimum version needed. A second file, go.sum, stores cryptographic hashes of those dependencies so downloads can be verified.
Most people use only two subcommands: go mod init once, when starting a project, and go mod tidy constantly, to make go.mod match the imports in the source. The other subcommands inspect or export the dependency graph.
go mod init example.com/shop # create go.mod go mod tidy # add missing, remove unused requirements go mod why golang.org/x/text # why is this needed? go mod graph # print the requirement graph
Try it
A go.mod file is plain text with a simple grammar, so a small program can read it. The examples parse one and then do the core job of go mod tidy: compare what the code imports with what the file requires.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Syntax
go mod <command> [arguments]
| Command | Description |
|---|---|
init [module-path] |
Create go.mod in the current directory. The path is usually the repository URL (github.com/you/app); for a throwaway project any name works. |
tidy |
Add requirements for imports that are missing and remove those no longer used. Also updates go.sum. Flags: -e keeps going on errors, -v explains removals, -diff prints changes without applying them, -compat=1.21 keeps checksums for an older Go. |
download [modules] |
Fetch modules into the module cache. With no arguments, downloads all dependencies of the main module. -json prints details. |
vendor |
Copy dependencies into a vendor/ directory, plus vendor/modules.txt. Builds use it automatically when go.mod says go 1.14 or later and the directory exists. -o dir changes the location. |
verify |
Check that cached modules still match go.sum and have not been modified. |
why [-m] [-vendor] packages |
Show the shortest import chain from your module to a package (or to a module with -m). |
graph [-go=version] |
Print the module requirement graph, one module requirement pair per line. |
edit |
Scripted edits of go.mod: -require, -droprequire, -replace, -dropreplace, -exclude, -go=1.24, -toolchain, -module, -fmt, -json, -print. |
go.mod directives
| Directive | Meaning |
|---|---|
module path |
The module's import path. A /v2 or higher suffix is required from major version 2. |
go 1.24 |
The minimum Go version. Since Go 1.21 it is enforced and decides language features. |
toolchain go1.24.2 |
A suggested toolchain, used by GOTOOLCHAIN switching. |
require path version |
A dependency at a minimum version. // indirect marks modules not imported by your own code. |
replace old => new |
Substitute a module with another path/version or a local directory. Only the main module's replaces count. |
exclude path version |
Forbid a specific version. |
retract version |
Declared in your own module to tell users a published version is broken. |
tool path |
Records a command dependency for go tool (Go 1.24). |
godebug key=value |
Default GODEBUG settings for the main module (Go 1.23). |
ignore dir |
Directories that patterns like ./... skip (Go 1.25). |
Usage notes
- Minimal version selection. Go picks the highest of the minimum versions requested anywhere in the graph, not the newest release. Upgrades happen only when you ask (
go get -u). Builds are therefore reproducible without a lock file. - Commit both files.
go.modandgo.sumbelong in version control.go.summay list more hashes than you directly use; do not edit it by hand, and letgo mod tidyfix it. - Run
tidybefore you commit, and in CI check that it changes nothing (go mod tidy -diffin newer versions, or run it and look atgit diff). go mod tidyconsiders tests of your packages and of the packages they import, and all build tags, so a dependency used only on Windows stays listed.- Private modules. Set
GOPRIVATE=example.com/*so Go skips the public proxy and checksum database for them. - Local development. A
replacepointing to a local folder is convenient but should not be committed in a published module, because other modules ignore yourreplacelines. Workspaces solve this better: see go work. - Proxy and checksums. Downloads go through
GOPROXY(defaultproxy.golang.org) and are checked againstsum.golang.org. See go env. - Vendoring is useful for offline builds and audits; keep it in sync with
go mod vendor, and CI should verify withgo mod vendorplusgit diff --exit-code. - Where modules live: the module cache is read-only under
$GOPATH/pkg/mod;go clean -modcacheremoves it.
Related
- go get, go list, go work, go install
- Lessons: Modules, Dependencies, Go Generate and Workspaces