Nx stores the cache in a per-user directory outside your workspace, ~/.nx/<id>/cache, where the id identifies the workspace rather than the folder it happens to sit in. Every checkout of one workspace shares that directory -- the main checkout, every worktree added to it, and a second clone -- so a task built in one is a cache hit in the others, and renaming or moving a checkout keeps its cache. Cache results are stored for a week before they get deleted.
You can customize the location in the nx.json file:
{ "cacheDirectory": "/tmp/mycache"}Why it is outside the workspace
Section titled “Why it is outside the workspace”Each workspace gets one directory, ~/.nx/<id>, holding both cache and databases.
Checkouts share it. A main checkout, every worktree added to it, and a separate clone all resolve to the same directory, so none of them rebuilds what another already has.
The id comes from the workspace's identity -- its Nx Cloud id where there is one, otherwise a key derived from the git remote -- so it does not change when you rename or move a checkout. A workspace with no derivable identity, such as a directory that is not a git repository, keeps its own copy.
An AI agent sandbox can reach it. A sandbox grants filesystem paths, and ~/.nx is spelled the same on every machine, so the grant can live in a settings file you commit. An absolute checkout path cannot. nx configure-ai-agents writes that grant into .claude/settings.json for Claude Code.
Opting out
Section titled “Opting out”Setting cacheDirectory opts out of the shared location: Nx uses what you configured, in the checkout that configures it. NX_CACHE_DIRECTORY, NX_WORKSPACE_DATA_DIRECTORY and NX_PROJECT_GRAPH_CACHE_DIRECTORY opt out the same way.
On Linux and macOS, a configured directory outside the workspace, and every directory above it, must belong to you, root, or the workspace owner, and the directory itself must not be writable by every user. Otherwise Nx stops with an error. To share a cache that another trusted account owns, such as a CI service user, set NX_ALLOW_INSECURE_DIRECTORIES=true.
When Nx falls back
Section titled “When Nx falls back”When Nx cannot use ~/.nx, the checkout keeps its own .nx directories instead. Two things cause it: Nx cannot make the directory owner-only, usually after a sudo nx run that kept your HOME and left it owned by root; or the process cannot write there at all, which is what an agent sandbox does.
Nx tells the second case apart by writing a marker file rather than by recognizing the caller, so a sandbox Nx has never heard of is covered as long as it denies the write. A sandbox that permits writes to ~/.nx is not falling back, and does not need to.
Temporary package installs, which nx add, nx migrate, nx init, and create-nx-workspace make, never fall back to the checkout. They use your per-user temp directory instead, but only when that directory and every directory above it can be written by no one but you and root. macOS gives each user such a directory, and a sandbox can set TMPDIR to one. Otherwise, such as with a shared /tmp on Linux, Nx stops with an error.
nx reset clears both the shared directory for the current workspace and the checkout's own. Nothing reclaims the directory belonging to a workspace you no longer have checked out anywhere, so remove those by hand.