How to fix Error: EPERM: operation not permitted, chmod 'file' in Node.js

Node.jsINTERMEDIATEHIGHUpdated Dec 9, 2025· 208 views

This error occurs when Node.js attempts a file system operation that the operating system denies due to insufficient permissions. It commonly happens during chmod, rename, unlink, or write operations, particularly on Windows with antivirus software or on Unix-like systems with incorrect file ownership.

Quick fix

Fixes EPERM

# Stop any running Node processes
# On Windows Task Manager: End all node.exe processes
# On macOS/Linux:
pkill -f node

# Then reopen a fresh terminal and retry the operation
  1. Close all programs accessing the project files
  2. Run command prompt or terminal as administrator
  3. Add antivirus exclusions for your project directory
  4. Remove read-only attributes and check file permissions
node.js — error
# Stop any running Node processes
# On Windows Task Manager: End all node.exe processes
# On macOS/Linux:
pkill -f node
# Then reopen a fresh terminal and retry the operation
Error: EPERM: operation not permitted, chmod 'file'

What this error means

The EPERM error code stands for "Error: PERMission denied" and indicates that the operating system prevented Node.js from completing a file system operation. When you use Node.js file system methods like fs.chmod(), fs.rename(), fs.unlink(), or fs.writeFile(), the underlying OS must grant permission for these operations. If the current user lacks sufficient privileges, the file is locked by another process, or security software blocks the operation, Node.js receives an EPERM error from the OS. This error is particularly common on Windows systems where antivirus software (especially Windows Defender with Tamper Protection) actively monitors and can block file operations in node_modules directories. On Unix-like systems (Linux, macOS), it typically occurs when attempting to modify files owned by another user or protected system files without proper permissions. Understanding the cross-platform differences is crucial: Windows has simpler permission models compared to Unix, and Node.js's chmod() has limited functionality on Windows since it only supports read/write permission changes.

Typical symptoms

  • npm install or npm operations fail with EPERM errors
  • File operations (chmod, rename, unlink) throw permission denied errors
  • Error occurs intermittently, working sometimes but failing other times
  • Operations succeed when running as administrator/root but fail otherwise
  • Build tools or bundlers fail to write output files
  • Code works on one machine but fails on another with identical code
  • Windows Defender or antivirus shows file access notifications

Common causes

  1. Antivirus software (especially Windows Defender) blocking file operations in node_modules
  2. File is locked by another process (IDE, terminal, or background service)
  3. User account lacks necessary permissions to modify the target file or directory
  4. File or directory is marked as read-only in the file system
  5. Windows Defender Tamper Protection preventing modifications to protected folders
  6. Attempting to modify files owned by a different user without sudo/admin rights
  7. File is currently open in an editor or being used by another application
  8. On Windows, directories can remain locked briefly after operations complete

How to fix "Error: EPERM: operation not permitted, chmod 'file'"

1Close all programs accessing the project files

Close your IDE (VS Code, WebStorm, etc.), any terminals running development servers, and any file explorers viewing the project directory:

bash
# Stop any running Node processes
# On Windows Task Manager: End all node.exe processes
# On macOS/Linux:
pkill -f node

# Then reopen a fresh terminal and retry the operation

File locks are a common cause of EPERM errors. Even hidden background processes can hold locks on files in node_modules, preventing modifications.

2Run command prompt or terminal as administrator

If the error occurs during npm operations or when modifying system-level files, run with elevated privileges.

On Windows:
- Right-click Command Prompt or PowerShell
- Select "Run as administrator"
- Navigate to your project directory and retry the operation

On macOS/Linux:

bash
# Use sudo for the specific operation that failed
sudo npm install

# Or change ownership of the project directory
sudo chown -R $USER:$USER /path/to/project

Avoid using sudo for regular npm operations when possible. If you frequently need sudo, your npm configuration may need adjustment to use a user-owned directory for global packages.

3Add antivirus exclusions for your project directory

Antivirus software, particularly Windows Defender, commonly blocks file operations in node_modules.

Windows Defender exclusions:
1. Open Windows Security > Virus & threat protection
2. Click "Manage settings" under Virus & threat protection settings
3. Scroll to "Exclusions" and click "Add or remove exclusions"
4. Add your project folder (e.g., C:\Users\YourName\projects)

Disable Tamper Protection temporarily:
1. Windows Security > Virus & threat protection
2. Manage settings > Tamper Protection > Toggle off
3. Retry the operation, then re-enable Tamper Protection

For other antivirus software, add the project directory or node_modules to the exclusion/whitelist in the antivirus settings. This is safe for development projects you trust.

4Remove read-only attributes and check file permissions

Ensure the target file or directory is not marked as read-only.

On Windows (Command Prompt):

batch
# Remove read-only attribute from a specific file
attrib -r "path\to\file"

# Remove read-only recursively from directory
attrib -r "path\to\directory\*" /s /d

On macOS/Linux:

bash
# Check current permissions
ls -la /path/to/file

# Make file writable by owner
chmod u+w /path/to/file

# Make entire directory tree writable
chmod -R u+w /path/to/directory

After removing read-only status, retry the operation that caused the EPERM error.

5Perform a clean reinstall with retries

If the error occurs during npm operations, do a complete clean reinstall. Windows directory locking may require retry logic.

On macOS/Linux:

bash
rm -rf node_modules
rm -f package-lock.json
npm cache clean --force
npm install

On Windows (PowerShell, may need multiple attempts):

powershell
# First attempt - close all programs first
Remove-Item -Recurse -Force node_modules -ErrorAction SilentlyContinue

# If locked, wait and retry
Start-Sleep -Seconds 2
Remove-Item -Recurse -Force node_modules -ErrorAction SilentlyContinue

# Then proceed
Remove-Item package-lock.json -ErrorAction SilentlyContinue
npm cache clean --force
npm install

Consider using graceful-fs or rimraf packages in build scripts for more reliable cross-platform file operations with automatic retry logic.

Advanced notes

Cross-platform Node.js permission differences: Node.js does not fully support Windows permissions. The fs.chmod() method only works reliably on Unix systems. On Windows, fs.chmod() can only toggle read/write permission and does not distinguish between user, group, or others. For truly cross-platform code, avoid relying on chmod() and instead use higher-level abstractions or platform-specific checks.

Graceful file operations: For production code that needs to handle file system operations robustly, use the graceful-fs library, which wraps fs methods with queuing and retry logic. The rimraf package also provides cross-platform recursive deletion with retry mechanisms for locked directories on Windows.

Docker and containerization: Inside Docker containers on Windows using WSL2 or Hyper-V, permission issues can occur when bind-mounting volumes. Use named volumes for node_modules instead of bind mounts: docker run -v /app/node_modules myapp. This avoids permission conflicts between host and container file systems.

CI/CD environments: In CI pipelines (GitHub Actions, Jenkins), EPERM errors can occur due to previous build artifacts being locked. Always use fresh environments or add cleanup steps with retry logic before builds. GitHub Actions' actions/cache can sometimes preserve locked files between runs.

File locking on Windows: Windows file locking behavior differs from Unix. A file can remain locked for milliseconds after a process closes it. Use retry logic with maxRetries option in fs.rm() or packages like retry-fs for operations that might hit transient locks.

Monorepo considerations: In monorepos with multiple packages, cross-package file operations during build steps may hit EPERM errors if builds run concurrently. Use build orchestration tools (Turborepo, Nx) that properly sequence operations and avoid file conflicts.

Frequently asked questions

What does "EPERM" mean?
js from completing a file system operation. writeFile(), the underlying OS must grant permission for these operations. js receives an EPERM error from the OS.
How do I fix "EPERM"?
This error occurs when Node.js attempts a file system operation that the operating system denies due to insufficient permissions. It commonly happens during chmod, rename, unlink, or write operations, particularly on Windows with antivirus software or on Unix-like systems with incorrect file ownership.
What causes "EPERM"?
Antivirus software (especially Windows Defender) blocking file operations in node_modules File is locked by another process (IDE, terminal, or background service) User account lacks necessary permissions to modify the target file or directory
Is the "EPERM" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading