Part of: Mac disk cleanup for developers: every cache, what it costs to rebuild (Developers)
Run go env GOMODCACHE to find the Go module cache. It is safe to clear, because Go downloads modules again when a project needs them. A plain delete may fail with “permission denied”, because Go makes the cache read-only on purpose.
A module is a Go library. Go keeps a copy of every module version your projects use, so they build the same way each time.
Find the caches
go env GOMODCACHE
go env GOCACHEGOMODCACHE is the downloaded modules. GOCACHE is a separate cache of compiled build output. On the Mac used to check this article, the first printed ~/go/pkg/mod and the second ~/Library/Caches/go-build.
To see the sizes:
du -sh "$(go env GOMODCACHE)" "$(go env GOCACHE)"The module cache also has a cache subfolder that holds downloaded archives. On the Mac used to check this article, the whole module cache was around a hundred megabytes. It grows with each project and version, and on Macs with many Go projects it can be much larger.
Why “permission denied”
Go writes the module cache with read-only permissions. This protects it: if you edit a file inside, it would silently change the code of every project that uses it. The side effect is that tools that delete folders, such as Finder or a basic delete in Terminal, may refuse.
The right way is to let Go clear its own cache. The go clean command has a -modcache option for the module cache and a -cache option for the build cache. Check go help clean on your Mac for the flags your version supports. The alternative of changing permissions on the whole cache and then deleting it works, but it is easy to point at the wrong folder, so prefer Go’s own command.
This article does not include the clean command line itself, because it removes the cache and was not run while checking the article. Look at the documentation, then run it once you are sure.
Safe, risky, never
- Safe: the module cache and the build cache, cleared with the go tool. Cost: re-download of modules and a slower next build.
- Risky: clearing the module cache offline, or when a module was pulled from the host and exists only in your cache. Also risky: clearing it while a build is running.
- Never: do not edit files inside
GOMODCACHE, and do not usechmodacross a broad path to force a delete. A mistake there hits other folders.
What it costs
The next go build or go test downloads the modules each project needs. If your go.sum file is present, Go checks the downloads against it, so you get the same code back. For most projects that is seconds to a minute. Clearing the build cache costs a full compile, which is slower for large projects.
If your company uses a private module proxy or private repositories, make sure you can reach them before you clear the cache.
How to clear it
- Check the paths and sizes with the commands above.
- Stop builds and editors that run Go tools in the background.
- Use Go’s own clean options, from
go help clean, for the module cache and the build cache you want to clear. - Run a build in one project to confirm downloads work.
Related caches
Rust has a similar split between a download cache and build output. See Rust target folders and the Cargo cache. For Python, see pip and conda caches, and for JavaScript see npm, Yarn and pnpm. The whole list is in the developer cleanup guide.
Worked example: check the size of the download folder
The module cache has a cache/download folder, which holds the archives Go downloaded. This read-only command shows its size:
du -sh "$(go env GOMODCACHE)/cache/download"On the Mac used to check this article, it was about 18 MB. The whole module cache was about 108 MB, so the downloads are a small part and most of the rest is unpacked module source. If you only want to know whether Go is a problem on your disk, these two numbers answer it in seconds.
Check that your project can rebuild
Before you clear the cache for a project you care about, make sure go.mod and go.sum are both in the project and committed. They list the modules and their checksums. With both, a fresh download is checked against what you used before.
If your project keeps copies of its dependencies in a vendor folder, it does not need the module cache to build. That is a way to build without a network, and it also means clearing the cache will not slow that project.
If something goes wrong
- “permission denied” on delete. Use Go’s own clean option, as described above, instead of changing permissions.
- A private module will not download after clearing. Your access setup is missing. Test it before you clear the cache next time.
- “checksum mismatch”. The module at the source changed, or the download was damaged. Do not ignore it. Compare with your last known good
go.sum. - The next build is much slower. That is the cost of re-downloading modules. Clearing the module cache does not empty the build cache, which is separate (
GOCACHE), so compiled output is only rebuilt if you clear that one too.
When not to clean
Skip it when the cache is small. A hundred megabytes is not worth a long first build. Clear it when it is large, or when a download looks damaged.
See sizes in a scan
DiskJoy is our product. Its scan reads your disk and shows how large these folders are, read-only. Cleanup is not built yet, so DiskJoy does not remove them today.
Frequently asked questions
Where is the Go module cache?
Run go env GOMODCACHE. On the Mac used to check this article it printed a folder named mod inside pkg in the go folder of the home directory. Build output is cached separately and go env GOCACHE shows where.
Why do I get permission denied when I delete the Go module cache?
Go marks the files in the module cache as read-only so they are not edited by accident. A plain delete can fail on them. Use the go tool to clear the cache, as described in its documentation.
Is it safe to delete the Go module cache?
Yes. Go downloads the modules your projects need again. The cost is a download and a rebuild of what depended on them.