Where Does Pants Keep Its Cache?
Where Pants keeps its local cache and named caches, what pants.toml configures, and what is safe to delete.
Last updated
Pants caches aggressively under ~/.cache/pants, with lmdb_store for subprocess results and named_caches for tool data like PEX environments. A separate launcher cache holds the interpreters Pants itself needs. The repo stays clean because almost nothing caches inside it.
Two pants.toml options relocate the main caches, and the launcher honors its own variable. Project outputs go to dist and workdir inside the build root instead, which are disposable by design. When a build misbehaves after an upgrade, wiping the cache is the standard first step.
Where Pants stores this, by platform
~/.cache/pants
Main cache root with lmdb_store and named_caches inside. The launcher keeps its own nce cache beside it on Linux. Relocate through pants.toml GLOBAL options or wipe freely; everything rebuilds. macOS mirrors the layout under Library/Caches.
~/Library/Caches/pants
Same structure as Linux under the macOS cache root. The launcher nce folder sits beside it. Version upgrades are the usual reason to clear both, since stale entries cause the oddest failures.
Frequently asked questions
how do I clear the Pants cache
Delete ~/.cache/pants to reclaim space; everything there rebuilds on demand. Keep pants.toml and BUILD files, which are the real configuration. In CI, cache lmdb_store and named_caches between runs keyed on inputs instead.
how do I move the Pants cache
Set local_store_dir and named_caches_dir in the GLOBAL section of pants.toml. Both accept absolute paths or repo-relative ones, plus a homedir placeholder. Keep cache dirs out of the build root or add them to pants-ignore.
are the nce and pants cache folders the same
No. The launcher cache holds interpreters and venvs for running Pants itself, keyed to the version in pants.toml. The main cache holds subprocess results and tool caches like PEX. Wiping the wrong one just costs a slow first run.
Notice an outdated path? Let us know.