npm cache clean --force: what it does and whether it is safe

By EgeTech LTD · October 6, 2026 · 2 min read

npm cache clean is one of the most copied commands in JavaScript troubleshooting threads, and one of the least useful. Here is what it actually does, why it needs a flag, and when it is worth running.

Where the npm cache is

npm config get cache

On a Mac the answer is usually ~/.npm. Inside it, the folder _cacache holds every package tarball and metadata file npm has downloaded. To see how much space it takes:

du -sh ~/.npm

On a machine that has been used for development for a while, it is commonly a few hundred megabytes to a few gigabytes.

What npm cache clean does

npm cache clean --force

It deletes the contents of that cache. The --force is required. If you leave it out, npm refuses and explains why:

npm error As of npm@5, the npm cache self-heals from corruption issues
npm error   by treating integrity mismatches as cache misses.  As a result,
npm error   data extracted from the cache is guaranteed to be valid.  If you
npm error   want to make sure everything is consistent, use `npm cache verify`
npm error   instead.  Deleting the cache can only make npm go slower, and is
npm error   not likely to correct any problems you may be encountering!

That message is the whole story. Modern npm checks every file it reads from the cache. A damaged entry is ignored and downloaded again, so the cache rarely needs repairing by hand.

Try npm cache verify first

npm cache verify

This checks the cache for consistency and removes content that nothing references. If you are chasing an install error, it is the gentler first step.

When clearing the cache does help

• You want the disk space back. This is the honest reason. The cache can be large and it is always safe to remove.
• A disk or network problem left half-written files, and npm cache verify does not fix it. Very rare, but this is what --force is for.
• You are about to give the laptop away and want it tidy.

It will not fix most EACCES, ENOTEMPTY or dependency-resolution errors. Those usually come from permissions, a broken node_modules, or a conflicting lockfile. Deleting node_modules and reinstalling is the better move. See can I delete node_modules.

What it costs

The next npm install downloads everything again. With a fast connection that is a minute. Offline, it fails: if you rely on the cache to work without internet, do not clear it before a flight.

The npx cache

npx keeps its own downloads inside the same cache folder. You can inspect and remove just those:

npm cache npx ls
npm cache npx rm

Other package managers have their own caches

npm is not the only one. pnpm, Yarn and Bun each keep a separate cache, and on a developer Mac they add up. See the pnpm store guide and how to clear the Yarn and Bun caches, or go through the full developer checklist.