There is no nx cache clean command, which is the first thing to know when a search for one brings you here. To clear the Nx cache, run nx reset; to skip it for one run, pass --skip-nx-cache. Both do more (or less) than the name suggests, and half the time "clear the cache" is not the fix you actually need. This is the complete map: what each reset flag clears, where the cache lives, how to skip or disable it, what to do about a remote cache, the two errors that usually send people looking, and the cases where clearing anything is treating the symptom.
Clear the Nx cache: nx reset and its flags
Run without flags, nx reset clears the local task cache and the workspace data Nx computes about your project graph, and stops the Nx daemon. In a workspace connected to Nx Cloud it also resets the Nx Cloud client. Each part has its own flag when you want to be surgical (Nx accepts the camelCase spellings such as --onlyCache too):
npx nx reset # cache + workspace data + stop the daemon
npx nx reset --only-cache # clear only the cached task outputs
npx nx reset --only-workspace-data # clear only cached project-graph metadata
npx nx reset --only-daemon # stop the daemon and clear its data (it restarts on demand)
npx nx reset --only-cloud # reset the Nx Cloud client (does not clear the remote cache)Knowing which one you need saves real time in a big workspace. Stale task outputs call for --only-cache. A project graph that does not reflect a file you just created - or a task that seems to run against old configuration - is workspace data or daemon state, not the task cache, so --only-workspace-data or --only-daemon is the targeted fix and your cached build outputs survive. None of these flags touch a remote cache; --only-cloud resets the local Nx Cloud client, not the artifacts stored in Nx Cloud.
Where the cache actually lives
Since Nx 23.2 the local task cache is shared between every checkout, worktree, and clone of a workspace: it lives in ~/.nx/<id>/cache in your home directory, where the id is derived from the workspace's Nx Cloud id or its git remote. Older versions keep it in .nx/cache in the workspace root (and very old ones in node_modules/.cache/nx). Nx also falls back to the checkout's own .nx directory when it cannot write to ~/.nx, for example inside a sandbox.
That change explains a lot of "I deleted .nx/cache and nothing happened" reports. Prefer nx reset --only-cache over deleting directories by hand: it clears whichever location the workspace really uses. Since 23.2 it also clears the shared directory, so it empties the cache for every checkout of the same workspace on that machine. Directories for workspaces you no longer have checked out are never reclaimed automatically; remove those under ~/.nx by hand.
The location is configurable - cacheDirectory in nx.json or the NX_CACHE_DIRECTORY environment variable - and setting either opts out of the shared location. That matters on CI: if your pipeline caches .nx/cache between jobs, either point it at ~/.nx or set NX_CACHE_DIRECTORY so the path you save is the path Nx writes. If a teammate's "clear the cache" advice did nothing, check where the workspace actually keeps it.
Skip the Nx cache for one run: --skip-nx-cache vs --skip-remote-cache
Most of the time the real goal is "prove this task actually executes", and deleting directories is the slow way to get it. Skip the cache at the call site instead:
# rerun even when results are cached; reads and writes neither local nor remote cache
npx nx run-many -t build --skip-nx-cache
# turn only the remote cache off for this run; the local cache still works
npx nx run-many -t build --skip-remote-cache
# environment-variable forms, useful in CI
NX_SKIP_NX_CACHE=true npx nx build my-app
NX_SKIP_REMOTE_CACHE=true npx nx build my-app--disable-nx-cache and --disable-remote-cache are accepted aliases for the same two flags. The difference is scope:
--skip-nx-cachebypasses caching completely for that run. Nothing is read from the local or remote cache, and nothing is written back, so the fresh result is not stored for anyone, including you. Use it to force a real execution.--skip-remote-cacheturns the remote cache off for both reads and writes, including Nx Cloud and self-hosted caches, while the local cache keeps working normally. It is the right switch for working offline or ruling the network out while debugging.
If you only want to stop talking to Nx Cloud, NX_NO_CLOUD=true (or --no-cloud) disconnects Nx Cloud for the run without affecting other remote caches.
Disable the Nx cache for a target
If a task should never be cached - deploys, publishes, migrations, anything with side effects or non-deterministic output - clearing and skipping are the wrong tools. Turn caching off for that target in configuration:
// nx.json - one target, every project
{
"targetDefaults": {
"deploy": { "cache": false }
}
}The same cache: false works in a single project's project.json when only one project misbehaves.
Clearing a remote cache (and why you usually should not)
Everything above operates on one machine. If your workspace shares results through a remote cache, nx reset does not touch it: the next run simply restores the same outputs over the network, which is usually what you want and occasionally very confusing when you were trying to force a rebuild. Nx has no CLI command that deletes remote entries.
That is by design. Remote entries are stored per input hash, and a well-behaved cache treats them as immutable. Change any input and Nx computes a new hash and a new entry, so an old entry can never be served for different inputs. Wiping the remote cache does not make results more correct; it throws away every teammate's and every CI runner's hits and makes the next pipeline run cold. If a fresh build gives a different result from a cached one, the real bug is an input the hash does not see - fix that and the bad entry simply stops being requested.
The genuine exceptions are a corrupt or poisoned artifact, or credentials that leaked. Then:
- Confirm it first: rerun with
--skip-remote-cache. If the problem disappears, the remote entry is the culprit; if not, it is local or in your configuration. - Change the hash rather than delete the entry: any change to the task's inputs, such as a bumped value in a
runtimeorenvinput, moves every affected task to a fresh key. - Evict on the server side. A self-hosted cache is your storage, so delete the entry or bucket prefix there; a managed cache expires entries on its own retention window. With Cachely, artifacts expire automatically after 20 days, and revoking a token cuts access immediately.
Our Nx remote cache guide covers how the remote layer fits together, including read-only tokens so pull requests can consume the cache without being able to write to it - the best protection against a poisoned entry in the first place.
Fixing common Nx cache errors
database is locked
Nx 20 and later keep cache metadata in a local SQLite database, and this error means two Nx processes tried to write to it at the same moment. It usually comes from several Nx commands running at once against one workspace - parallel CI jobs in the same checkout, or a cache directory on a shared or network drive. To fix it:
- Upgrade Nx; later releases retry busy database operations instead of failing.
- Run one
nx run-manyornx affectedwith--parallelinstead of several Nx invocations side by side. - Keep the cache directory on a local disk, not a network share.
- Stop any stuck process and run
nx resetto clear the workspace data and restart the daemon.
No such file or directory (os error 2)
This comes from Nx copying task outputs into or out of the cache and finding a path missing. The usual causes are a broken symlink inside the outputs, a declared output the task never produces, or a corrupt cache entry. Run the task with --verbose to see the failing path, then fix the symlink or narrow the target's outputs to what it really writes. If the configuration is right, clear the local copy with nx reset --only-cache and confirm with --skip-nx-cache. If the error follows a remote hit, a local reset will not help: rerun with --skip-remote-cache to confirm, then evict the entry server-side.
When clearing the cache is the wrong fix
Recurring cache trouble is nearly always a configuration problem wearing a disguise. Three patterns account for most of it:
- You clear the cache on a schedule because results go stale. Stale results mean a file that affects the output is missing from the task's
inputs, so its changes never invalidate the hash. Find it and declare it - the cache is doing exactly what the configuration says. - Hits restore nothing. A task with undeclared
outputscaches the terminal output but not the artifact, so a "hit" leavesdist/empty. Declare every output path the task produces. - Misses you cannot explain. Something volatile - a timestamp, an absolute path, an environment variable - is feeding the hash. Audit the target's
inputs(and its dependencies' inputs, vianpx nx graph) for over-broad patterns and missing exclusions rather than clearing anything.
All three are inputs-and-outputs problems, and tuning them is the highest-leverage cache work in an Nx workspace. The full walkthrough is in Nx cache not working? Fix cache misses with inputs and outputs.
Quick reference
nx reset- clear local cache and workspace data, and stop the daemon; add--only-cache,--only-workspace-data,--only-daemon, or--only-cloudto scope it.~/.nx/<id>/cache(Nx 23.2+) or.nx/cache(older) - where the local cache lives;nx reset --only-cacheclears whichever one the workspace uses.--skip-nx-cacheorNX_SKIP_NX_CACHE=true- force execution for one run; no cache is read or written.--skip-remote-cacheorNX_SKIP_REMOTE_CACHE=true- remote off (reads and writes), local cache unaffected.cache: false- permanently exclude a target that should never be cached.- None of these touch a shared remote cache - change the hash or evict server-side if an entry must truly disappear.