Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
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.

Go Reading a go.mod file

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.

Go What go mod tidy does, in miniature

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

Terminal
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.mod and go.sum belong in version control. go.sum may list more hashes than you directly use; do not edit it by hand, and let go mod tidy fix it.
  • Run tidy before you commit, and in CI check that it changes nothing (go mod tidy -diff in newer versions, or run it and look at git diff).
  • go mod tidy considers 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 replace pointing to a local folder is convenient but should not be committed in a published module, because other modules ignore your replace lines. Workspaces solve this better: see go work.
  • Proxy and checksums. Downloads go through GOPROXY (default proxy.golang.org) and are checked against sum.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 with go mod vendor plus git diff --exit-code.
  • Where modules live: the module cache is read-only under $GOPATH/pkg/mod; go clean -modcache removes it.