Victor's room

Overview & Root Cause Summary: The error npm ERR! code ENOTEMPTY syscall rename ... errno -39: directory not empty, rename occurs during npm install, npm update, or package removals when npm attempts an atomic folder rename operation inside node_modules, but the operating system rejects the operation because a background process or file lock is actively holding an open handle to files inside that directory.

Understanding the Root Causes

• Active Running Node Processes: Local development servers (e.g., Vite, Next.js, Webpack, Nodemon) or testing runners running in another terminal window actively watching and locking files inside node_modules.
• Antivirus & Windows Defender Scans: Real-time file system protection (especially Windows Defender or corporate endpoint security) intercepting and scanning newly extracted package binaries, temporarily preventing directory moves.
• Orphaned Staging Directories: Interrupted or cancelled previous installations leaving behind stale .staging or temporary cache folders that prevent clean directory overwrites.
• IDE & File Indexer Locks: Text editors like VS Code, WebStorm, or continuous search indexers scanning dependencies simultaneously during package lifecycle operations.

Step 1: Quick Fix (Terminate Zombie Processes & Clean Staging)

Ensure that all active Node runtimes are closed before attempting to clean temporary staging directories.

# 1. Terminate all running Node.js processes
# On Linux / macOS:
killall -9 node

# On Windows (PowerShell):
Stop-Process -Name node -Force -ErrorAction SilentlyContinue

# 2. Delete corrupted staging and cache folders inside node_modules:
rm -rf node_modules/.staging
rm -rf node_modules/.cache

# 3. Retry the installation:
npm install

Step 2: Clean Slate Reinstallation (Nuclear Option)

If corrupted metadata or nested dependency links persist, perform a complete purge of local modules and verify npm’s internal cache.

# 1. Remove node_modules and existing lockfile:
# On Linux / macOS:
rm -rf node_modules package-lock.json

# On Windows (PowerShell):
Remove-Item -Recurse -Force node_modules, package-lock.json

# 2. Force clean npm global cache:
npm cache clean --force

# 3. Perform a clean dependency installation:
npm install

Step 3: Addressing Windows Defender & File Locking

On Windows systems where real-time indexing causes recurring rename failures, configure folder exclusions or disable optional audit checks.

# Option A: Run npm with reduced auxiliary overhead
npm install --no-audit --no-fund

# Option B: Add your development project root to Windows Defender exclusions (PowerShell as Admin):
# Add-MpPreference -ExclusionPath "C:\path\to\your\projects"

# Option C: Use npm clean-install in automated or CI environments:
npm ci

Verification & Testing Steps

Verify that your dependency graph is intact and that lifecycle scripts execute cleanly without filesystem lock errors.

# 1. Verify that npm recognizes all installed root dependencies:
npm list --depth=0

# 2. Run your local development server or build script:
npm run build

Summary Comparison Table