Blog
3 min read

What Is node_modules? (And When to Delete It)

node_modules is the folder where npm installs your project's dependencies. Why it's so big, why it must never go into Git, when deleting it and reinstalling fixes things, the right commands on Mac, Linux and Windows, and how to reclaim disk space across old projects.

Every JavaScript project has a folder called node_modules. It's often the biggest thing on your disk, and "delete node_modules and reinstall" is one of the most common fixes on the internet. Here's what it is.

What it is

When you run npm install, npm reads your package.json, downloads every package your project needs — and every package those packages need, and so on — and puts them all in node_modules. (What are npm and package.json?)

Your app imports from there:

import express from 'express' // loaded from node_modules/express

Why it's so big

You might list 20 dependencies, but each has its own, which have their own. A typical React or Next.js project ends up with hundreds or thousands of packages and hundreds of megabytes. It's a running joke for a reason.

It must never go into Git

node_modules can be rebuilt any time from package.json and the lock file. Committing it bloats the repository enormously and causes conflicts. Your .gitignore should contain:

node_modules/

(.gitignore explained)

What should be committed is the lock file (package-lock.json, pnpm-lock.yaml, yarn.lock or bun.lock), which records the exact versions installed. (package-lock.json explained)

When deleting it helps

Reinstalling from scratch fixes problems caused by a messy install:

  • Strange errors after switching branches or pulling changes
  • "Cannot find module" for a package you know is installed (Cannot find module)
  • Errors after upgrading Node.js (packages with compiled parts need rebuilding)
  • An install that was interrupted
  • Weird version conflicts after manual edits

It won't fix bugs in your own code, or a genuinely incompatible set of versions. (npm ERESOLVE errors)

How to delete it and reinstall

Mac / Linux / WSL / Git Bash:

rm -rf node_modules
npm install

Windows PowerShell:

Remove-Item -Recurse -Force node_modules
npm install

On Windows, deleting through File Explorer can be painfully slow or fail on long paths; the command line is better. npx rimraf node_modules also works on any system.

Should you delete the lock file too?

Usually not. Deleting package-lock.json makes npm pick new versions of everything, which can introduce new problems. Only do it deliberately, when you want to refresh all versions — then test thoroughly.

npm ci: the clean install

npm ci

Deletes node_modules for you and installs exactly what's in the lock file. It's what you should use on servers and in CI. (Set up CI with GitHub Actions)

Reclaiming disk space

Old projects each keep their own node_modules. To find them:

npx npkill

It lists every node_modules under the current folder with its size and lets you delete them. You can always reinstall when you return to a project.

pnpm saves space by storing each package version once on your disk and linking it into projects. (npm vs pnpm vs Yarn vs Bun)

The summary

  • node_modules = installed dependencies, rebuilt from package.json + lock file.
  • Never commit it; always commit the lock file.
  • rm -rf node_modules && npm install fixes many broken-install problems.
  • Use npm ci on servers; npx npkill to free disk space.

EasySpawn installs your dependencies cleanly on every deploy and keeps them off your laptop entirely if you develop on the server. See how it works or join the waitlist.

Related: What Are npm and package.json? · What Is package-lock.json? · npm ERR! code ENOENT · How to Update Dependencies Safely

Keep reading