go mod download: Usage, Options & Common CI Errors
Pre-download modules into the cache before building.
go mod download fetches the modules named in go.mod (or all of them) into the local module cache without building. Running it early in CI isolates dependency download from compilation and caches well.
What it does
Downloads module zips and metadata into $GOPATH/pkg/mod and verifies them against go.sum. It does not compile anything, so a subsequent go build runs against a warm cache.
Common usage
go mod download # download all modules in go.mod
go mod download all # the full module graph
go mod download -x # print the commands it runs
go mod download -json # machine-readable outputCommon CI error: checksum mismatch
go mod download fails with "verifying ...: checksum mismatch" when go.sum disagrees with what the proxy served (tampering, a force-pushed tag, or a stale sum). Fix: if the change is legitimate, run go mod tidy locally to refresh go.sum and commit it; otherwise investigate the source. For proxy timeouts, set GOPROXY to a reliable mirror.
Options
| Flag | Effect |
|---|---|
| all | Download the whole module graph |
| -x | Print executed commands |
| -json | JSON output |
| GOPROXY env | Module proxy to fetch from |
Using this in CI
- Set the shell explicitly and enable
set -euo pipefail; the default runner shell does not stop on the first error inside a multi-line block. - Pin the tool version. An unpinned build tool turns a runner image update into a build break on unchanged code.
- Prefer non-interactive and batch flags. Progress output designed for a terminal bloats CI logs and can hang without a TTY.
- Write machine-readable output (JSON, JUnit) to a file and upload it as an artifact, so a failure is diagnosable without re-running the job.