npm install n8n fails – fix for ERESOLVE, EACCES, gyp ERR, EPERM, isolated-vm and node-gyp errors

Complete fix guide for every npm install n8n error – ERESOLVE, EACCES, gyp ERR, EPERM, isolated-vm, and more

Who this is for: Developers and DevOps engineers who self‑host n8n and encounter npm install failures on Linux, macOS, Windows, or Apple Silicon. This guide covers every error you’ll hit running npm install -g n8n — from ERESOLVE peer dependency conflicts to gyp ERR node-gyp failures, EACCES permission denied, EPERM on Windows, isolated-vm compile errors, and node version mismatches. We cover this in detail in the n8n Installation Errors Guide.

Quick Diagnosis

# Use a supported Node LTS
nvm install 20 && nvm use 20

# Clean npm cache & reinstall
npm cache clean --force && rm -rf node_modules package-lock.json
npm install --production

# Create a local npm prefix
mkdir "${HOME}/.npm-global"
npm config set prefix "${HOME}/.npm-global"

# Add it to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="${HOME}/.npm-global/bin:$PATH"

sudo apt-get update && sudo apt-get install -y build-essential python3

brew install python@3.11 libtool automake pkg-config

npm config set registry https://registry.npmjs.org/ && npm install --verbose

npm install -g n8n --legacy-peer-deps

# Run PowerShell as Administrator
Remove-Item -Recurse -Force node_modules
npm cache clean --force
npm install -g n8n

nvm install 20 && nvm use 20
npm install -g n8n

npm cache clean --force
npm install -g n8n@latest

npm install -g npm@latest
npm install -g n8n

*Run the block that matches your error, then retry npm install in the n8n project folder.*

1. Why the npm install step fails for n8n?

If you encounter any docker installation error n8n resolve them before continuing with the setup.

n8n compiles native modules (sqlite3, bcrypt, @n8n.io/cli, isolated-vm) with node‑gyp. Failures usually stem from one (or more) of the following root causes:

Identifying the exact cause guides you to the correct remedy.

2. Verify Node.js version compatibility

If you encounter any windows installation error n8n resolve them before continuing with the setup.

n8n requires Node.js between 20.19 and 24.x (inclusive). LTS 20 or LTS 22 are the recommended production choices. Node 18 is no longer supported. Node 25 causes isolated-vm compile failures.

Check the current version

node -v   # e.g. v20.19.0
npm -v    # should be 10.x or higher

Switch to a supported LTS (recommended 20.x or 22.x)

nvm install 20 && nvm use 20

nvm install 20.19.0
nvm use 20.19.0

# Install nvm first if not present
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20 && nvm use 20

EEFA note: Pin the Node version in production via .nvmrc, Docker FROM node:20‑bullseye, or CI configuration to avoid accidental upgrades. Never rely on nvm inside a Docker container — base the image on the correct Node LTS tag instead.

2a. Fix npm ERR! code ERESOLVE – the peer dependency conflict

This is the most searched npm install n8n error in 2024–2025. It happens because npm 7 introduced strict peer dependency enforcement. npm 6 treated peer dependency conflicts as warnings and installed anyway. npm 7+ treats them as hard errors and stops the install completely.

When you see this:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: n8n@x.x.x
npm ERR! Found: @langchain/core@1.x.x
npm ERR! Could not resolve dependency:
npm ERR! peerOptional @langchain/core@"~0.1.29" from @getzep/zep-cloud

npm is saying: package A needs version 1.x of a dependency, but package B needs version 0.1.x, and it can’t install both in strict mode. n8n’s AI/LangChain integrations frequently trigger this because those packages update aggressively.

Fix 1: Use --legacy-peer-deps (recommended)

This flag tells npm to fall back to the old npm 6 resolution algorithm — peer dependency conflicts become warnings again, not errors. It is the safest ERESOLVE fix:

npm install -g n8n --legacy-peer-deps

To set it permanently for a specific project (add a .npmrc file in the project root):

echo "legacy-peer-deps=true" > .npmrc
npm install -g n8n

Fix 2: Use --force (last resort)

--force bypasses all safety checks, not just peer deps. It can cause silent runtime breakage. Use it only in throw-away dev environments or if --legacy-peer-deps still fails:

npm install -g n8n --force

Fix 3: Update npm itself first

Older npm 7.x and 8.x versions had bugs in their ERESOLVE handling that were fixed in later releases. Before anything else, try upgrading npm:

npm install -g npm@latest
npm install -g n8n

–legacy-peer-deps vs –force: --legacy-peer-deps only relaxes peer dependency resolution — everything else stays strict. --force ignores all conflicts and warnings entirely. Always try --legacy-peer-deps first. If n8n starts and runs correctly, you’re done. These peer conflicts are almost always between optional AI/LangChain packages that don’t affect core workflow execution.

3. Clean the npm environment

A stale cache or mismatched lockfile often hides the real error.

Purge the npm cache

npm cache clean --force

Remove existing modules & lockfile

rm -rf node_modules package-lock.json

Re‑install with reproducible lockfile handling

npm ci   # fails fast if lockfile mismatches
# fallback if no lockfile exists
npm install --production

npm ci guarantees a deterministic install, preventing version drift that can trigger native‑module compilation errors.

4. Install required build tools (node‑gyp prerequisites)

*Install the C/C++ toolchain and Python 3 for your platform.*

4.1 Ubuntu / Debian

sudo apt-get update
sudo apt-get install -y build-essential python3 pkg-config libsqlite3-dev

4.2 CentOS / RHEL

sudo yum groupinstall "Development Tools"
sudo yum install -y python3 gcc-c++ make

4.3 macOS (Homebrew)

brew install python@3.11 pkg-config libtool automake sqlite3

4.4 Windows

1. Install the Windows build tools (run PowerShell as Administrator):

npm install --global --production windows-build-tools

2. Ensure Python 3 is on the PATH.

3. Alternatively, install Visual Studio Build Tools (Desktop development with C++) and the official Python installer.

5. Resolve permission errors

5.1 Prefer project‑scoped installs

# Inside your n8n project folder
npm install --save-dev

5.2 Fix the global npm directory (no sudo needed)

mkdir "${HOME}/.npm-global"
npm config set prefix "${HOME}/.npm-global"

Add the new bin directory to your shell profile (~/.bashrc, ~/.zshrc, etc.):

export PATH="${HOME}/.npm-global/bin:$PATH"

Reload the profile or open a new terminal.

5.3 Verify the fix

npm root -g   # should point to ~/.npm-global/lib/node_modules
npm install -g n8n   # should succeed without EACCES

5a. Fix EPERM: operation not permitted on Windows

Windows users frequently hit this error during npm install n8n or after an interrupted install attempt:

npm warn cleanup [Error: EPERM: operation not permitted, rmdir 'node_modules\@n8n\n8n-nodes-langchain\dist']
  errno: -4048,
  code: 'EPERM'

The cause is Windows Defender, antivirus software, or the Windows Search indexer locking files inside node_modules while npm tries to clean up. The fix:

Step 1: Exclude node_modules from Windows Defender

Go to Windows Security → Virus & threat protection → Manage settings → Exclusions and add your project folder.

Step 2: Delete node_modules with elevated permissions

# Run PowerShell as Administrator
Remove-Item -Recurse -Force .\node_modules
Remove-Item -Force package-lock.json

Step 3: Reinstall

npm cache clean --force
npm install -g n8n

If the error persists, try installing with --legacy-peer-deps or switching to Docker — Windows is the hardest environment for native npm module compilation and Docker eliminates all of these OS-level issues in one step.

5b. Fix npm install n8n on Apple Silicon (M1 / M2 / M3 Mac)

Apple Silicon Macs running arm64 architecture have specific issues with native node-gyp module compilation. The most common errors after upgrading macOS or Node.js on M1/M2:

gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2
# or
Error: dlopen(...node): tried: ... mach-o, but wrong architecture

Fix 1: Install Xcode Command Line Tools

This is the most common missing prerequisite on fresh or recently upgraded Macs:

xcode-select --install

Fix 2: Use the arm64 version of Node via nvm

If you installed nvm or Node.js under Rosetta 2 (x86 emulation), native modules compiled for arm64 will fail. Reinstall nvm natively:

# Check your current architecture
node -e "console.log(process.arch)"
# Should show: arm64 (not x64)

# If it shows x64, reinstall nvm in native arm64 terminal
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.zshrc
nvm install 20
nvm use 20

Fix 3: Clear and reinstall after Node switch

npm cache clean --force
npm install -g n8n

Fix 4: Use Docker (most reliable on M1/M2)

If native compilation keeps failing on Apple Silicon, Docker with the official n8n image sidesteps all architecture issues entirely. The n8n Docker image is built for both amd64 and arm64:

docker run -it --rm \
  -p 5678:5678 \
  -v ~/.n8n:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

After upgrading macOS (e.g. to Sonoma or Sequoia), Xcode Command Line Tools sometimes need to be reinstalled even if they were previously present. Run xcode-select --install again before troubleshooting anything else.

5c. Fix isolated-vm node-gyp compile failure (Node 22+ / Node 25)

As of 2025, the most common npm install n8n failure on fresh Linux servers is this:

npm error path /home/user/.npm-global/lib/node_modules/n8n/node_modules/isolated-vm
npm error command failed
npm error command sh -c node-gyp-build || node-gyp rebuild --release -j max
npm error gyp info using node@25.7.0 | linux | x64
npm error gyp ERR! build error

isolated-vm is n8n’s sandboxing module for Code nodes. It uses native C++ bindings that must be compiled for your exact Node.js ABI (application binary interface). The isolated-vm package does not support Node 25 (unstable) and has intermittent issues on Node 22. The fix is always the same: use Node LTS 20.

# Step 1 — switch to Node LTS 20
nvm install 20 && nvm use 20

# Step 2 — verify
node -v   # must show v20.x.x

# Step 3 — clean install
npm cache clean --force
npm install -g n8n

In Docker, use node:20-bullseye or the official n8n image, never node:latest which resolves to Node 25+ at time of writing.

6. Alternative installation paths (when npm still fails)

curl -L https://github.com/n8n-io/n8n/releases/download/<version>/n8n-linux-x64.tar.gz | tar -xz && ./n8n

7. Advanced troubleshooting checklist

Address any failing item before re‑running npm install.

8. Real‑world error log examples & interpretation

8.1 node-gyp cannot find Python

gyp ERR! stack Error: Can't find Python executable "python", you can set the PYTHON env variable.

Fix: Install Python 3 and expose it to node‑gyp:

export PYTHON=$(which python3)
npm install

8.2 Engine mismatch

npm ERR! engine Unsupported engine
npm ERR! engine Not compatible with your version of node: expected ">=20.19 <25", got "18.20.0"

Fix: Switch to Node 20 or 22 (see §2). Node 18 is no longer supported by n8n as of 2025.

8.3 Permission denied

npm ERR! code EACCES
npm ERR! syscall open
npm ERR! path /usr/local/lib/node_modules/n8n/package.json

Fix: Use a user‑owned npm prefix (see §5) or, only if absolutely necessary, reinstall with sudo after understanding the security impact.

8.4 ERESOLVE peer dependency conflict

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! While resolving: n8n@1.x.x
npm ERR! Found: @langchain/core@1.1.8
npm ERR! Could not resolve dependency:
npm ERR! peerOptional @langchain/core@"~0.1.29" from @getzep/zep-cloud@1.0.6

Fix: Use --legacy-peer-deps (see §2a). This is an npm 7+ strictness issue, not an n8n bug.

8.5 ETARGET – no matching version for @n8n/config

npm error code ETARGET
npm error notarget No matching version found for @n8n/config@1.43.0.
npm error notarget In most cases you or one of your dependencies are requesting
npm error notarget a package version that doesn't exist.

Fix: This is a stale npm cache issue — the local registry manifest is behind the published packages. Run:

npm cache clean --force
npm install -g n8n@latest

8.6 Unsupported URL Type “workspace:*”

npm ERR! Unsupported URL Type "workspace:": workspace:*

Fix: Your npm version is too old. The workspace: protocol requires npm 7 or higher. Upgrade npm first:

npm install -g npm@latest
npm install -g n8n

8.7 EPERM: operation not permitted (Windows)

npm warn cleanup [Error: EPERM: operation not permitted,
  rmdir 'D:\project\node_modules\@n8n\n8n-nodes-langchain\dist']
{ errno: -4048, code: 'EPERM', syscall: 'rmdir' }

Fix: Windows Defender or file indexer is locking the folder. See §5a for the full fix sequence.

8.8 Hundreds of “npm warn deprecated” — is my install broken?

npm warn deprecated inflight@1.0.6: This module is not supported, and leaks memory.
npm warn deprecated rimraf@3.0.2: Rimraf versions prior to v4 are no longer supported
npm warn deprecated gauge@4.0.4: This package is no longer supported.
npm warn deprecated glob@7.2.3: Glob versions prior to v9 are no longer supported

These are warnings, not failures. n8n’s dependency tree includes packages like inflight, rimraf, glob, and gauge that have issued deprecation notices. npm prints these as a courtesy — they do not stop the install from completing. If npm install -g n8n ends with added X packages and exits cleanly, n8n is installed correctly. Scroll past the warnings and look for an actual npm error code line if something is genuinely wrong.

9. Verify your n8n install succeeded

After running npm install -g n8n, confirm it actually worked before assuming there is a problem. A successful global install looks like this in the terminal:

added 638 packages in 2m
# No "npm error code" lines — deprecation warnings above are fine

Check the installed version

n8n --version
# Expected output: 1.x.x (current release version)

Start n8n and confirm it runs

n8n start
# Expected: "Editor is now accessible via: http://localhost:5678"

Quick smoke test with npx (no global install required)

npx n8n
# Downloads and runs n8n without global install — useful for testing

Confirm n8n is in PATH

which n8n          # Linux/macOS — should return a path
where n8n          # Windows — should return the install location

If n8n --version throws “command not found” after a clean install, your global npm bin directory is not in PATH. Re-check §5.2 to configure the user-owned npm directory and add it to your shell profile.

10. EEFA (Expert Experience, Field‑tested Advice)

• Never run npm install as root on a production server – it masks permission problems that surface later when the service runs under a non‑privileged user.
• Pin the Node version in CI/CD (.nvmrc, Docker FROM node:20-bullseye) to eliminate “works on my machine” failures. Node 20 is the safest pin for n8n in 2025.
• Cache native‑module binaries: after a successful install, copy the generated node_modules into a version‑controlled artifact (e.g., a Docker layer) to avoid recompilation on every deploy.
• Alpine Linux caution – its musl libc can cause node‑gyp to fail for optional dependencies. Prefer the node:20‑bullseye base image, or install musl-dev and python3 inside Alpine.
• On Windows, always disable or add exclusions to Windows Defender for your project folder before running npm install on large packages like n8n. The file lock issues during install are almost always antivirus-related.
• --legacy-peer-deps is safe for n8n — the peer dependency conflicts are almost always in optional AI/LangChain packages that don’t affect core workflow execution. If n8n starts and your workflows run, the install is fine.
• If you’re on a VPS with limited RAM (under 1 GB), npm install can silently fail due to OOM during native module compilation. Add a swap file or use the pre-built Docker image instead.

All commands assume a Unix‑like shell; adapt paths for Windows PowerShell as needed.