How to fix npm ERR! code ECIWARN npm ERR! `npm ci` requires a clean node_modules folder in npm

npmBEGINNERLOWUpdated Dec 3, 2025· 140 views

This error occurs when running npm ci with an existing node_modules directory. Remove node_modules before running npm ci, or let npm ci handle the cleanup in newer versions.

Quick fix

Fixes npm ERR! code ECIWARN npm ERR! `npm ci` requires a clean node_modules folder

rm -rf node_modules
npm ci
  1. Remove node_modules before npm ci
  2. Update npm to version 7+
  3. Fix CI/CD caching configuration
  4. Add cleanup to CI scripts
npm — error
rm -rf node_modules
npm ci
npm ERR! code ECIWARN
npm ERR! `npm ci` requires a clean node_modules folder

What this error means

npm ci is designed to perform clean installations. In older npm versions (before npm 7), it required node_modules to not exist. The command would refuse to run if it detected an existing node_modules directory. This behavior ensures that you're getting a completely fresh installation from the lockfile without any leftover files from previous installs that might cause inconsistencies. In npm 7+, npm ci automatically removes node_modules before installing, so this error is less common with modern npm versions.

Typical symptoms

  • npm ci fails with "requires a clean node_modules folder" error
  • Error occurs in CI/CD after caching node_modules
  • Local development environment triggers this error
  • Running npm ci after npm install causes this error
  • Using older npm version (pre-7.x)

Common causes

  1. node_modules directory exists from previous install
  2. CI/CD caching node_modules between runs
  3. Developer ran npm install before npm ci
  4. Using npm version older than 7.x
  5. Incomplete cleanup from failed previous install

How to fix "npm ERR! code ECIWARN npm ERR! `npm ci` requires a clean node_modules folder"

1Remove node_modules before npm ci

Manually clean before running npm ci:

bash
rm -rf node_modules
npm ci

This is the simplest fix and works across all npm versions.

2Update npm to version 7+

Modern npm automatically handles this:

bash
npm install -g npm@latest
npm --version  # Should be 7.x or higher

npm 7+ removes node_modules automatically when running npm ci.

3Fix CI/CD caching configuration

If you're caching node_modules in CI, adjust your config:

yaml
# GitHub Actions - cache npm cache, not node_modules
- uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}

- run: npm ci  # Fresh install each time, but uses cached downloads

Don't cache node_modules directly with npm ci.

4Add cleanup to CI scripts

Add explicit cleanup in CI configuration:

yaml
# Example for various CI systems
steps:
  - name: Clean install
    run: |
      rm -rf node_modules
      npm ci

Advanced notes

npm ci behavior by version:

- npm 6.x and earlier: Fails if node_modules exists
- npm 7.x and later: Automatically removes node_modules first

For faster CI builds, cache the npm cache directory instead of node_modules:

| CI System | Cache Path |
|-----------|------------|
| GitHub Actions | ~/.npm |
| GitLab CI | ~/.npm |
| CircleCI | ~/.npm |
| Travis CI | ~/.npm |

This gives you fast downloads while ensuring clean installs.

If you must cache node_modules (for speed), use npm install instead of npm ci, but be aware this may cause non-reproducible builds:

yaml
- uses: actions/cache@v3
  with:
    path: node_modules
    key: ${{ runner.os }}-modules-${{ hashFiles('**/package-lock.json') }}

- run: npm install  # Uses cached modules if available

However, npm ci with npm cache is generally preferred for CI/CD.

Frequently asked questions

What does "npm ERR! code ECIWARN npm ERR! `npm ci` requires a clean node_modules" mean?
npm ci is designed to perform clean installations. In older npm versions (before npm 7), it required node_modules to not exist. The command would refuse to run if it detected an existing node_modules directory.
How do I fix "npm ERR! code ECIWARN npm ERR! `npm ci` requires a clean node_modules"?
This error occurs when running npm ci with an existing node_modules directory. Remove node_modules before running npm ci, or let npm ci handle the cleanup in newer versions.
What causes "npm ERR! code ECIWARN npm ERR! `npm ci` requires a clean node_modules"?
node_modules directory exists from previous install CI/CD caching node_modules between runs Developer ran npm install before npm ci
Is the "npm ERR! code ECIWARN npm ERR! `npm ci` requires a clean node_modules" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading