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.
Fixes npm ERR! code ECIWARN npm ERR! `npm ci` requires a clean node_modules folder
rm -rf node_modules
npm cirm -rf node_modulesnpm cinpm ERR! code ECIWARNnpm ERR! `npm ci` requires a clean node_modules folder
On this page
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.
Manually clean before running npm ci:
rm -rf node_modules
npm ciThis is the simplest fix and works across all npm versions.
Modern npm automatically handles this:
npm install -g npm@latest
npm --version # Should be 7.x or highernpm 7+ removes node_modules automatically when running npm ci.
If you're caching node_modules in CI, adjust your config:
# 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 downloadsDon't cache node_modules directly with npm ci.
Add explicit cleanup in CI configuration:
# Example for various CI systems
steps:
- name: Clean install
run: |
rm -rf node_modules
npm cinpm 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:
- uses: actions/cache@v3
with:
path: node_modules
key: ${{ runner.os }}-modules-${{ hashFiles('**/package-lock.json') }}
- run: npm install # Uses cached modules if availableHowever, npm ci with npm cache is generally preferred for CI/CD.