How to fix Error: EPERM: operation not permitted, symlink 'target' -> 'link' in Node.js

Node.jsINTERMEDIATEHIGHUpdated Dec 9, 2025· 309 views

This error occurs when Node.js attempts to create a symbolic link on Windows without administrator privileges. Windows restricts symlink creation to admin accounts or users with specific developer mode permissions. The error commonly appears when using fs.symlink() or tools that auto-link dependencies, especially in development environments or CI/CD pipelines.

Quick fix

Fixes EPERM

# Create a test directory and symlink
mkdir test-dir
node -e "const fs = require('fs'); fs.symlinkSync('./test-dir', 'test-link');"
  1. Enable Developer Mode on Windows 10/11 (simplest solution)
  2. Run Node.js with administrator privileges
  3. Avoid symlinks in code using Node.js alternatives
  4. Update Node.js and npm to latest versions
node.js — error
# Create a test directory and symlink
mkdir test-dir
node -e "const fs = require('fs'); fs.symlinkSync('./test-dir', 'test-link');"
Error: EPERM: operation not permitted, symlink 'target' -> 'link'

What this error means

The EPERM error when creating symlinks on Windows indicates that the operating system denied the permission to create a symbolic link. Unlike Unix-like systems where regular users can often create symlinks, Windows has stricter requirements: symbolic links require either administrator privileges or Developer Mode to be enabled (Windows 10 1904 and later). This distinction is crucial for Node.js developers: the same fs.symlink() code that works seamlessly on macOS or Linux will fail on Windows unless the process runs with elevated privileges. Symlinks are commonly needed by Node.js package managers (npm, yarn), build tools, and development workflows. Understanding Windows' symlink restrictions and the available workarounds is essential for cross-platform Node.js development.

Typical symptoms

  • fs.symlink() or fs.symlinkSync() throws EPERM errors on Windows
  • npm or yarn operations fail during workspace setup with symlink errors
  • Tools like lerna or monorepo managers fail to create linked packages
  • Operations work perfectly on Linux/macOS but fail only on Windows
  • The same code works when running the terminal as administrator
  • CI/CD pipelines fail on Windows runners while succeeding on Linux runners
  • Build tools that auto-link dependencies throw permission denied errors

Common causes

  1. User account lacks administrator privileges required for symlink creation on Windows
  2. Developer Mode is not enabled on Windows 10/11 (required for non-admin symlinks)
  3. The process running Node.js is not executed with elevated privileges
  4. Antivirus or security software blocking symlink operations
  5. Running on Windows Home edition which has stricter symlink restrictions
  6. The filesystem or directory is marked with restricted permissions
  7. Network shares or mounted drives that do not support symlinks

How to fix "Error: EPERM: operation not permitted, symlink 'target' -> 'link'"

1Enable Developer Mode on Windows 10/11 (simplest solution)

Developer Mode allows non-administrator users to create symlinks. This is the recommended approach for development environments.

Windows 10 (build 14393 and later) and Windows 11:
1. Open Windows Settings (Win + I)
2. Go to Privacy & Security > Developer settings
3. Toggle "Developer Mode" to ON
4. Restart your computer or log out and back in

Verify it worked:

bash
# Create a test directory and symlink
mkdir test-dir
node -e "const fs = require('fs'); fs.symlinkSync('./test-dir', 'test-link');"

Developer Mode grants unprivileged users the right to create symlinks, making it the best solution for local development. This change persists across Windows updates.

2Run Node.js with administrator privileges

If enabling Developer Mode is not an option (locked-down corporate machines), run your Node.js process as administrator.

On Windows (Command Prompt as Admin):
1. Right-click Command Prompt or PowerShell
2. Select "Run as administrator"
3. Navigate to your project and run your Node.js command:

bash
npm install
# or
node script.js

Creating a shortcut to run always as admin:
1. Right-click your terminal shortcut
2. Select "Properties"
3. Click "Advanced"
4. Check "Run as administrator"
5. Click OK

This approach works but is less convenient for development because you must always open the admin terminal. Use Developer Mode instead for better workflow.

3Avoid symlinks in code using Node.js alternatives

If you control the code, refactor to avoid fs.symlink() where possible, or use alternatives:

Option 1: Use npm workspaces or local dependencies

json
{
  "workspaces": [
    "packages/*"
  ]
}

Instead of fs.symlink(), npm/yarn handle linking automatically without permission issues.

Option 2: Use relative requires

javascript
// Instead of:
// fs.symlinkSync('./src', './lib');

// Use:
const src = require('../src');

Option 3: Use junction points instead of symlinks

javascript
// Junctions have fewer restrictions than symlinks
fs.symlinkSync(target, link, 'junction');
// or
fs.symlinkSync(target, link, 'dir');

Junction links do not require administrator privileges and work on all Windows versions.

4Update Node.js and npm to latest versions

Older versions of npm or Node.js may have stricter symlink behavior. Updating often helps:

bash
# Check current Node.js version
node --version

# Update Node.js (using a version manager like nvm-windows or volta is recommended)
# On Windows with chocolatey:
choco upgrade nodejs

# Or manually download from https://nodejs.org/

# Verify the update
node --version
npm --version

Newer versions of npm and Node.js have improved handling of Windows symlink restrictions and may provide better error messages.

5Check filesystem type and antivirus restrictions

Verify the filesystem and antivirus settings:

Check filesystem type:

powershell
# Check the filesystem of your drive
fsutil fsinfo volumeinfo C:

# Look for the filesystem type (should be NTFS)

Verify antivirus is not blocking symlinks:
1. Temporarily disable antivirus or add exclusions for your project directory
2. Try the symlink operation again
3. If it succeeds, add the directory to your antivirus whitelist

For network shares:
If the target is on a network share or UNC path, verify:
- The share supports symlinks (not all do)
- The user account has create permissions
- Try storing the project on a local drive instead

Most antivirus software does not block symlinks, but some security-focused configurations may.

Advanced notes

Symlink variations on Windows: Windows supports three types of links: symlinks (hardest to create, most flexible), junction points (no privilege requirement, directory-only), and hard links (no privilege requirement, file-only). The fs.symlinkSync(target, path, type) third parameter can be 'file', 'dir', 'junction', or 'fifo'. For cross-platform code targeting Windows, always default to 'junction' for directories when possible, as they have minimal restrictions.

Group Policy and Enterprise environments: On managed corporate machines, Group Policy may disable symlink creation even with Developer Mode or admin privileges. Check with your IT department if symlinks are explicitly blocked via Group Policy (Settings > Policies > Computer Configuration > Administrative Templates > System > Filesystem).

WSL2 and Docker integration: When running Node.js in WSL2 (Windows Subsystem for Linux), symlinks work like Unix systems and do not require admin privileges. If possible, run development workflows in WSL2 to avoid Windows symlink restrictions entirely.

npm and workspace symlinks: Modern npm (v7+) automatically handles symlinking for workspaces and local dependencies without requiring explicit fs.symlink() calls. If you use 'npm workspaces', npm manages the linking internally and avoids triggering the Windows symlink permission error.

Cross-platform build tools consideration: Tools like nx, turborepo, and lerna create symlinks internally for monorepo management. When running these tools on Windows:
- For development: enable Developer Mode as a one-time setup
- For CI/CD: run the job with elevated privileges or use Docker containers running Linux
- Document the Windows setup requirement in your project README

Backward compatibility with Windows 7/8: Windows 7 and 8 do not have Developer Mode. On these systems, administrator privileges are the only way to create symlinks. If supporting legacy Windows versions, consider using junction points or avoiding symlinks altogether.

Frequently asked questions

What does "EPERM" mean?
The EPERM error when creating symlinks on Windows indicates that the operating system denied the permission to create a symbolic link. Unlike Unix-like systems where regular users can often create symlinks, Windows has stricter requirements: symbolic links require either administrator privileges or Developer Mode to be enabled (Windows 10 1904 and later). symlink() code that works seamlessly on macOS or Linux will fail on Windows unless the process runs with elevated privileges.
How do I fix "EPERM"?
This error occurs when Node.js attempts to create a symbolic link on Windows without administrator privileges. Windows restricts symlink creation to admin accounts or users with specific developer mode permissions. The error commonly appears when using fs.symlink() or tools that auto-link dependencies, especially in development environments or CI/CD pipelines.
What causes "EPERM"?
User account lacks administrator privileges required for symlink creation on Windows Developer Mode is not enabled on Windows 10/11 (required for non-admin symlinks) The process running Node.js is not executed with elevated privileges
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