go clean — Middle¶

1. The flag map¶

Flag	What it removes
(none)	Build outputs for the named packages in their source dirs (the executable, `_obj`/`_test` leftovers)
`-i`	Also the installed binary/archive (what `go install` produced)
`-r`	Apply recursively to all dependencies of the named packages
`-cache`	The entire build cache (`GOCACHE`)
`-testcache`	Expire all cached test results
`-modcache`	The entire module download cache (`GOMODCACHE`)
`-fuzzcache`	Cached fuzz corpora generated by `go test -fuzz`
`-n`	Print actions without executing
`-x`	Print and execute the commands

The cache flags (-cache, -testcache, -modcache, -fuzzcache) operate globally, not per-package.

2. Build cache vs module cache¶

These are different things and clean differently:

Build cache (GOCACHE, default ~/.cache/go-build): compiled package objects, action results, cached test results. go clean -cache and -testcache target this.
Module cache (GOMODCACHE, default $GOPATH/pkg/mod): downloaded source of dependencies. go clean -modcache targets this.

go env GOCACHE GOMODCACHE

Wiping the build cache means recompiling; wiping the module cache means re-downloading.

3. `-testcache` vs `-count=1`¶

Both force tests to re-run, but differently:

go clean -testcache    # expires ALL cached test results globally
go test -count=1 ./...  # bypasses the cache for THIS run only

Use -count=1 for a one-off forced run; use go clean -testcache when you want every future test invocation to start fresh until results are recached.

4. The read-only module cache caveat¶

Files in GOMODCACHE are stored read-only so builds cannot accidentally mutate dependency source. A naive rm -rf "$(go env GOMODCACHE)" can hit permission errors. Always use:

go clean -modcache

which handles the read-only bits correctly. (Since Go 1.14, chmod/permission handling is built in.)

5. Previewing with `-n`¶

Before any destructive clean, preview:

go clean -n -cache       # shows it would remove $GOCACHE
go clean -n -modcache    # shows it would remove $GOMODCACHE
go clean -n -i ./...     # shows installed artifacts that would be removed

-n prints the underlying file operations without performing them — essential for the global cache flags.

6. Cleaning installed binaries¶

go clean by default removes build outputs left in the package's source directory, not the installed binary in GOBIN. To remove the installed artifact:

go clean -i ./cmd/mytool    # remove the installed binary/archive too

Note there is still no general go uninstall; -i removes the artifact for packages you name, but you often just rm "$(go env GOPATH)/bin/tool".

7. Fuzz corpus cache¶

go test -fuzz generates corpus entries cached under the build cache's fuzz directory. To clear them:

go clean -fuzzcache

Useful when a corpus grows large or you want fuzzing to start from the seed corpus only. (Committed seed corpora in testdata/fuzz are not affected — only the generated cache.)

8. How it fits the dev loop¶

You should rarely clean in normal development — the caches are correct by construction. Legitimate triggers:

CI disk pressure: periodically go clean -modcache/-cache on long-lived runners.
Reproducing "from scratch": go clean -cache && go build ./... to confirm a cold-cache build.
Test result staleness from external state: go clean -testcache.
Toolchain experiments: wipe caches when switching between unusual toolchain configurations.

9. Trade-offs¶

Action	Reclaims	Costs
`-testcache`	a little	tests re-run once
`-cache`	build cache size	full recompile next build
`-modcache`	often the most disk	re-download dependencies
`-fuzzcache`	fuzz corpus size	fuzzing restarts from seeds

Cleaning caches always trades disk savings for slower subsequent builds/downloads.

10. Summary¶

go clean removes build outputs and, with flags, the global build (-cache), test (-testcache), module (-modcache), and fuzz (-fuzzcache) caches. Use -testcache to re-run tests fresh, -modcache to reclaim the most disk (it handles read-only files correctly), and -n to preview destructive operations. -i removes installed artifacts. In normal development you rarely need any of these — the caches are safe and content-addressed.