How to Download Go Module Dependencies and Use the Module Cache

If you already have a Go module, start by running go test from the directory containing go.mod. A test can download modules it needs. Use go mod download when your goal is to prefetch modules into the local cache; use go get when you intend to add or change a dependency requirement. Those commands answer different questions: What does this test need? What should be downloaded ahead of time? What version should this project require?

Start with the module files

A module has a go.mod file at its root. It declares the module path and dependency requirements, each identified by a module path and version. Here is a small illustrative manifest:

module example.com/hello

require rsc.io/quote v1.5.2

The require line identifies rsc.io/quote as a dependency at v1.5.2. That version comes from an example in the Go modules introduction; it is not a recommendation for a new project. Run the commands below from the directory containing your project’s go.mod, rather than treating the example manifest as something to copy.

The Go command also maintains go.sum, which records expected cryptographic hashes for specific module versions. It uses those hashes to check that future downloads retrieve the same content. Keep both go.mod and go.sum in version control: the former records requirements, while the latter helps detect unexpected changes to downloaded content.

Let tests fetch what they need

From the module root, run:

go test

For a module with a package in that directory, this tests the package and can fetch modules needed for the test. The Go modules introduction shows go test finding and downloading dependencies. A successful test tells you the test completed; it is not an instruction to add a particular requirement or proof that the resulting dependency set is what you intended.

If imports or requirements have changed, review the module files afterward. For a deliberate addition or version change, choose a module path and version and use go get rather than relying on a test to make that decision for you.

Prefetch modules without confusing the cache with the manifest

If you want to download modules ahead of a build, run:

go mod download

This downloads modules to the local module cache. It is useful when preparing an environment before the build step, but it is not the command to choose when your purpose is to declare a new project dependency. For an intentional addition or version change, use go get with the module and version you actually want:

go get example.com/[email protected]

Both the path and version are placeholders, not a dependency recommendation or a command to paste unchanged. Replace them with the module path and version you have chosen. A go get dependency example is documented as updating go.mod and creating or updating go.sum in this Go modules guide. Review those changes rather than inferring the intended version from a successful command alone.

Align metadata and inspect the result

After adding, removing, or changing imports and requirements, tidy the module metadata and inspect the resulting dependency set:

go mod tidy
go list -m all
git status --short -- go.mod go.sum
git diff -- go.mod go.sum

go mod tidy adds missing requirements and removes unused ones. go list -m all lists the current module and its dependencies, including their versions. Read that list to check what the project now resolves; command success alone does not tell you whether those are the versions you meant to keep. The status check can also reveal a newly created module file that would not appear in an ordinary diff of tracked files. Review changes to both go.mod and go.sum before committing them.

These files are not the downloaded dependency source. go.mod describes requirements, go.sum holds integrity hashes, and the module cache holds downloaded modules used by builds. To find the cache selected by your Go environment—and see where module downloads are configured to come from—ask the Go command:

go env GOMODCACHE GOPROXY

GOMODCACHE reports the module-cache location. Avoid assuming a fixed path: the Go modules wiki documents that the location can be configured. GOPROXY configures the servers used to download dependencies; inspect its reported value when a download source matters to your project.

If you work with private code, configure GOPRIVATE for the relevant private module paths so they do not use the wrong proxy or checksum route. The Go modules wiki also names GONOPROXY and GONOSUMDB as finer-grained alternatives when that distinction is needed.

The practical workflow is to test, prefetch only if you need to, choose versions deliberately with go get, and then tidy and inspect the result. Commit dependency metadata, not a developer’s local cache as a substitute. The declared requirements and recorded hashes are what you can review with the project; cache and proxy settings determine where local copies are stored and where downloads come from.