Symptoms & Diagnosis
The npm error eperm operation not permitted typically occurs during package installation or global updates. It signals that Node.js lacks the necessary filesystem permissions to modify, rename, or delete a specific file or directory.
On Windows, this is frequently caused by a process locking the node_modules folder, such as an IDE, a running server, or an antivirus scanner. On macOS or Linux, it usually points to a mismatch between the user’s permissions and the global /usr/local/lib/node_modules directory.
Common signs include a terminal output ending with errno: -4048 or code: 'EPERM'. You might see a specific file path listed, indicating exactly where the access was denied.
Troubleshooting Guide
Before diving into complex fixes, try closing your code editor (like VS Code) and stopping any running development servers. If the error persists, use the following steps.
1. Run Terminal as Administrator
On Windows, right-click your Command Prompt or PowerShell and select Run as Administrator. This grants npm the elevated privileges required to modify system folders.
# For macOS/Linux, use sudo for global installs
sudo npm install -g [package-name]2. Clear the NPM Cache
Corrupted cache files can sometimes trigger permission conflicts. Clearing the cache forces npm to fetch fresh data.
npm cache clean --force3. Compare Common Solutions
Use the table below to determine which fix applies to your specific environment:
| Solution | System | Primary Cause |
|---|---|---|
| Run as Admin | Windows | Lack of write access to Program Files |
| Delete node_modules | Universal | Locked or corrupted local folders |
| Update NPM | Universal | Internal bugs in older npm versions |
| Disable Antivirus | Windows | Real-time scanning locking files |
4. Delete and Reinstall node_modules
If the error occurs within a specific project, manually deleting the local folders often solves the “locked file” issue.
rm -rf node_modules
rm package-lock.json
npm installPrevention
The best way to prevent EPERM errors is to avoid using sudo or Administrator mode for every command. This is best achieved by using a Node Version Manager (NVM).
Using nvm (Windows) or nvm (macOS/Linux) installs Node.js in your user directory rather than system-protected folders. This ensures you always have the correct permissions to install packages globally without intervention.
Additionally, configure your antivirus to exclude your project workspace folders. This prevents the scanner from locking files while npm is trying to move them, which is a frequent trigger for the EPERM error on Windows machines.