Fix: npm ERR! ENOTEMPTY: directory not empty, rename

The Error

You run npm install and get:

npm ERR! code ENOTEMPTY
npm ERR! syscall rename
npm ERR! path /home/user/project/node_modules/some-package
npm ERR! dest /home/user/project/node_modules/.some-package-xyz
npm ERR! errno -39
npm ERR! ENOTEMPTY: directory not empty, rename '/home/user/project/node_modules/some-package' -> '/home/user/project/node_modules/.some-package-xyz'

Or on Windows:

npm ERR! code EPERM
npm ERR! syscall rename
npm ERR! path C:\Users\user\project\node_modules\some-package
npm ERR! errno -4048
npm ERR! EPERM: operation not permitted, rename 'C:\Users\user\project\node_modules\some-package'

npm tried to move a directory during installation and failed because the target directory already has files in it, or the operating system blocked the operation.

Why This Happens

During npm install, npm moves packages around in node_modules — renaming directories as part of its installation algorithm. This rename operation fails when:

• Corrupted npm cache. The local cache has stale or corrupted entries that conflict with the installation.
• Concurrent npm processes. Two npm commands running at the same time modify the same node_modules directory.
• Stale node_modules. A previous interrupted installation left node_modules in an inconsistent state.
• File locking on Windows. An editor, file watcher, or antivirus is holding a lock on files inside node_modules.
• Filesystem race condition. On network drives (NFS, SMB) or Docker volumes, file operations may not be atomic.
• npm bug. Some npm versions have known issues with the rename operation on specific platforms.

Fix 1: Delete node_modules and Reinstall

The most reliable fix. Remove the corrupted state and start fresh:

rm -rf node_modules
npm install

On Windows (if rm is not available):

rmdir /s /q node_modules
npm install

If rm -rf itself fails with permission errors, close all editors and terminals that might have files open in node_modules, then try again.

Pro Tip: If you frequently need to delete node_modules, use the npx npkill command to interactively find and remove node_modules directories across your system. It is faster than manual deletion and shows how much disk space each one uses.

Fix 2: Clear the npm Cache

A corrupted cache causes npm to create conflicting files during installation:

npm cache clean --force

Then reinstall:

rm -rf node_modules
npm install

Verify the cache is intact:

npm cache verify

This checks the cache for consistency and removes corrupted entries.

The --force flag is required because npm warns against cleaning the cache (it is usually self-healing). In this case, cleaning is necessary.

Fix 3: Delete package-lock.json and Reinstall

If the lock file is inconsistent with the current node_modules state:

rm -rf node_modules package-lock.json
npm install

This regenerates both node_modules and package-lock.json from scratch. Warning: This might change your dependency versions if package.json uses ranges (^, ~). If you need exact reproducibility, only delete node_modules and keep package-lock.json.

If the lock file has dependency resolution conflicts rather than rename errors, see Fix: npm ERESOLVE unable to resolve dependency tree.

Fix 4: Fix Windows File Locking

On Windows, EPERM or ENOTEMPTY errors are often caused by other processes locking files in node_modules:

Close these before running npm install:

• VS Code (or any editor with file watchers)
• Terminal windows with cd inside the project
• File Explorer windows showing node_modules
• Windows Defender real-time scanning
• Docker Desktop file sharing

Disable Windows Defender for your project directory:

1. Open Windows Security → Virus & threat protection
2. Click “Manage settings” under Virus & threat protection settings
3. Scroll to Exclusions → Add an exclusion
4. Add your project directory

Use PowerShell as administrator:

Remove-Item -Recurse -Force node_modules
npm install

Common Mistake: Running npm install while VS Code is open with the project. VS Code’s file watcher monitors node_modules for changes, which can lock files during npm’s rename operations. Close VS Code or disable the file watcher for node_modules by adding it to the files.watcherExclude setting.

Fix 5: Fix Concurrent npm Operations

If two terminal tabs are running npm commands on the same project:

# Check for running npm processes
ps aux | grep npm

# On Windows
tasklist | findstr node

Kill any stale npm processes:

# Linux/macOS
kill <pid>

# Windows
taskkill /PID <pid> /F

Fix: Remove the npm lock file:

npm creates a .package-lock.json in node_modules to prevent concurrent operations. If a previous npm process crashed, this lock might be stale:

rm -rf node_modules/.package-lock.json
npm install

Fix 6: Fix Docker and Container Environments

When running npm install inside a Docker container with a mounted volume, the host filesystem may not support atomic renames:

Fix: Copy files instead of mounting node_modules:

# In Dockerfile
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .

Do not mount node_modules from the host. Use a named volume or exclude it:

# docker-compose.yml
services:
  app:
    volumes:
      - .:/app
      - /app/node_modules  # Anonymous volume — npm installs inside container

The anonymous volume for node_modules means the container’s npm-installed packages are not mapped to the host filesystem, avoiding cross-platform rename issues.

If npm install fails with a different error inside Docker, check if the issue is related to npm ERR! cb() never called or network connectivity.

Fix 7: Use npm ci Instead of npm install

npm ci (clean install) is designed for CI/CD and avoids many rename issues:

npm ci

npm ci differences from npm install:

• Deletes node_modules entirely before installing
• Installs exact versions from package-lock.json
• Does not modify package-lock.json
• Faster because it skips the resolution step

This is often the fix for ENOTEMPTY errors because it starts with a clean node_modules every time.

Fix 8: Update npm

Some versions of npm have bugs that cause ENOTEMPTY errors. Update to the latest:

npm install -g npm@latest

If updating npm itself fails with permission errors, see Fix: npm EACCES permission denied global install.

Check your current version:

npm --version

Known problematic versions: npm v6 had several ENOTEMPTY bugs on Windows that were fixed in npm v7+. If you are on npm v6, upgrading to v9 or v10 resolves most of these issues.

Fix 9: Fix NFS and Network Drive Issues

On network filesystems (NFS, CIFS/SMB, shared Docker volumes), file operations may not be atomic:

Symptoms:

• ENOTEMPTY errors are intermittent
• The error happens on different packages each time
• The same project installs fine on a local filesystem

Fix: Install on a local filesystem:

Move the project to a local drive:

cp -r /mnt/nfs/project ~/local-project
cd ~/local-project
npm install

Fix: Use --prefer-offline to reduce network operations:

npm install --prefer-offline

Fix: Increase the npm retry settings:

npm config set fetch-retries 5
npm config set fetch-retry-mintimeout 20000
npm install

Still Not Working?

If the error persists after trying all fixes:

Try yarn or pnpm. Alternative package managers handle node_modules differently and may not have the same rename issues:

# Using yarn
npx yarn install

# Using pnpm
npx pnpm install

pnpm uses a content-addressable store and hard links instead of copying packages, which avoids most rename and disk space issues.

Check filesystem permissions. The user running npm must have write permissions to the project directory:

ls -la node_modules/

If owned by root, fix permissions:

sudo chown -R $(whoami) node_modules/

For permission denied errors during npm install, see Fix: EACCES permission denied mkdir.

Check disk space. Running out of disk space during install can cause partial renames that leave directories in an inconsistent state:

df -h .

Use the --verbose flag for more information:

npm install --verbose

This shows detailed logs of every file operation, which can help identify exactly which package and file causes the error.

Check for antivirus interference. Some antivirus software (McAfee, Norton, Kaspersky) lock files immediately after creation for scanning. This interferes with npm’s rapid create-rename cycle. Temporarily disable real-time scanning or exclude the project directory.