What does npm:ENOTEMPTY mean?

npm hit ENOTEMPTY because it tried to replace or remove a directory that still contains files, often during install, cleanup, or rename steps.

npm ERR! code ENOTEMPTY

Q: How do I prevent npm:ENOTEMPTY in CI?

Keep npm cache and project directories owned by the build user. Avoid running project installs as root unless you know exactly why you need it. Ensure CI runners have enough disk space and sensible file descriptor limits.

Fix it fast

Most likely: npm tried to remove or replace a directory that still had files in it, often because another process, watcher, editor, sync tool, or antivirus tool touched it during install.

1. Confirm this is your error

npm ERR! code ENOTEMPTY

2. Check the cause

ls -la <failing-directory>
lsof +D <failing-directory>
ps aux | grep npm
npm config get cache

3. Apply the safe fix

# Stop anything using the directory, then retry.
npm cache verify
npm install

# If the failing directory is stale node_modules content, remove that specific stale directory and reinstall.

4. Verify it works

npm install
npm cache verify

Don't use unsafe shortcuts

Do not run multiple installs against the same project at the same time.
Do not use sudo to force removal, it can leave root-owned files behind.
Do not delete broad project directories before checking the exact directory npm could not remove.

What Local Operation Failed

The remote service may be fine. This class of error is usually about what the local machine was allowed to read, write, cache, or execute.

Fix the local path, cache, or permissions

Identify the path npm is failing on (look for the last referenced file path in the error output).

Delete the target directory manually (common offender:node_modules) and retry the install.

Retry after cleaning local state when safe (common:remove node_modules and retry install).

Manual filesystem checks

If a directory removal fails, confirm no process is using it (platform-specific:lsof +D <dir>).

Why the Local Machine Blocked It

A background process is locking files while npm is trying to rename/remove them.

Verify the Local Path Is Usable Again

Re-run the original command and confirm the filesystem error no longer appears.

If this is a permission fix, confirm new files in node_modules are owned by the expected user.

How npm writes files during install

npm got far enough to read or write local state, but the host filesystem blocked the operation. Ownership drift, read-only mounts, stale caches, full disks, and restrictive permissions all show up in this layer. These are usually local machine or runner problems rather than upstream service problems, so fix the path, ownership, or free space before changing dependency versions.

Prevent Local State Drift

To prevent this, keep npm cache and project directories owned by the build user, avoid running project installs as root unless you know exactly why you need it, and ensure CI runners have enough disk space and sensible file descriptor limits.

Docs and source code

github.com/npm/cli/blob/417daa72b09c5129e7390cd12743ef31bf3ddb83/lib/commands/cache.js

This is a representative filesystem write path during npm operations. Filesystem codes like this are raised by Node/OS when this write fails. - GitHub

        break
      }
      output.standard(`Deleted: ${key}`)
      await cacache.rm.entry(cachePath, key)
      // XXX this could leave other entries without content!
      await cacache.rm.content(cachePath, entry.integrity)
    }