go clean can wipe more than you meant: past the project's own build artefacts sit shared caches that every other Go project on the machine relies on. This guide previews before it deletes, separates a package clean from a cache clean, and checks the project still works afterwards. Allow about ten minutes for a routine project clean, plus time to redownload dependencies if you clear a cache.
This guide describes the installed Go command on this machine, Go 1.26.1 from the golang-go:amd64 package. The Debian manual page is dated 15 March 2022, while the installed command confirms the cache flags shown here. A different Go release can have different flags or cache details, so check its local help first.
Start in the module or package tree you intend to clean. Do not run a broad clean from an unrelated directory just because the command happens to work there. Confirm the executable and version:
$ command -v go
/usr/bin/go
$ go version
go version go1.26.1 linux/amd64There is normally no need for sudo. A project clean should be unprivileged. If files are owned by another account, stop and fix the ownership or switch to the correct account rather than making a habit of running Go as root.
Checkpoint: you are in the intended project directory, and go version reports the toolchain you expect.
Use -n to print the removal commands without executing them. This is the safest way to see what the installed tool considers removable for the selected package:
$ go clean -nThe preview can be empty. Modern Go puts most build results in a temporary directory or the shared build cache, so there may be no old object files left in the source tree. This command is mainly useful for files left by older tools, manual builds, tests compiled with go test -c, or similar workflows.
For a named package, pass its import path or a package pattern after the flags:
$ go clean -n ./...
$ go clean -n example.com/project/cmd/serverRead the complete preview before running the same command without -n. The output is a list of removal commands, not a report of files already deleted.
Once the preview looks right, run the corresponding clean:
$ go clean ./...With a package argument, Go examines the matching source directories. The installed manual lists old _obj/ and _test/ directories, generated _testmain.go, test.out, build.out, object files such as *.o, binaries produced by go build, test binaries, and shared objects produced by SWIG. The exact set depends on the package tree and the files actually present.
The -r flag extends the clean to dependencies of the named packages. Use it only when that wider scope is intentional:
$ go clean -n -r ./...
$ go clean -r ./...The -i flag also removes the corresponding installed archive or binary that go install would create. Treat -i as a separate decision, especially on a development machine where another project may rely on an installed command:
$ go clean -n -i ./...
$ go clean -i ./...Warning: these removals are destructive. Source files are not a backup of generated binaries or test output. If you might need an artefact for debugging, copy it to a named evidence directory before cleaning. If you delete it by accident, rerun the relevant build or test command to recreate it; there is no undo command in go clean.
Cache flags affect shared data outside the current package directory. Do not reach for them as a reflex when a local clean would do.
-cache removes the entire Go build cache. Future builds will recompile more work.-testcache expires cached test results. Future tests run again instead of reusing those results.-modcache removes the entire module download cache, including unpacked source for versioned dependencies. Future builds may need network access and may fail if those versions are no longer reachable.-fuzzcache removes files stored in the build cache for fuzz testing, which can make fuzzing less effective until equivalent coverage inputs turn up again. It does not remove files in a project's testdata directory.Preview each cache operation before running it:
$ go clean -n -cache
$ go clean -n -testcache
$ go clean -n -modcache
$ go clean -n -fuzzcacheThen run only the operation you actually selected, for example:
$ go clean -cacheCache flags do not need a package argument; they target the Go cache configured for the current user and environment. Check the locations before a large cleanup:
$ go env GOCACHE GOMODCACHE GOPATHDo not combine several cache flags in a script unless the wider reset is deliberate and documented. A clean cache is recoverable by rebuilding or redownloading, but it can cost time, bandwidth and access to private modules.
go clean is quiet on success, so verify with the operation that matters. Rebuild a package to repopulate normal build outputs:
$ go build ./...
$ go test ./...If the project has a dedicated test or build command, use that instead. A successful clean does not prove the project still builds, and a successful build does not prove a module cache purge was harmless to an offline workflow. For a local artefact clean, inspect the working tree afterwards:
$ git status --shortUnexpected source changes are not a normal result of go clean. Stop and investigate rather than restoring files blindly; the command should not touch tracked Go source, module files or test data.
-n or -x. Check the exit status in a script and run the build or tests you actually care about.-x as a preview. -x prints removal commands as they execute. Use -n when you want no changes at all.-r adds dependencies, and cache flags target shared caches. Read the command as a scope declaration.go clean -n was read before any destructive clean.git status --short shows no unexpected source changes.