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

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:

# 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.

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:

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.

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

Option 1: Use npm workspaces or local dependencies

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

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

Option 2: Use relative requires

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

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

Option 3: Use junction points instead of symlinks

// 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.

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

# 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.

Verify the filesystem and antivirus settings:

Check filesystem type:

# 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.