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

n8n Installation & Setup Errors / Leave a Comment

npm install n8n error fix guide

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

Symptom Quick Fix (run in terminal)
npm ERR! code ELIFECYCLE or gyp ERR! Fix Node version & clean install

# 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
EACCES permission denied Configure a user‑owned global npm directory

# 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"
Missing node‑gyp or python Install build prerequisites

Ubuntu/Debian

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

macOS (Homebrew)

brew install python@3.11 libtool automake pkg-config
npm install hangs / times out Force registry & verbose mode

npm config set registry https://registry.npmjs.org/ && npm install --verbose
npm ERR! code ERESOLVE — peer dependency conflict Use legacy peer dependency resolution

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

If that fails, try: npm install -g n8n --force (last resort only)
EPERM: operation not permitted (Windows) Delete locked node_modules and reinstall as Administrator

# Run PowerShell as Administrator
Remove-Item -Recurse -Force node_modules
npm cache clean --force
npm install -g n8n
isolated-vm node-gyp compile failure (Node 22+/25) Switch to Node LTS 20 — isolated-vm does not support Node 25

nvm install 20 && nvm use 20
npm install -g n8n
npm error code ETARGET — No matching version found for @n8n/config Clear npm cache — stale registry metadata is the cause

npm cache clean --force
npm install -g n8n@latest
Unsupported URL Type “workspace:*” Your npm is too old — upgrade npm first

npm install -g npm@latest
npm install -g n8n
Hundreds of “npm warn deprecated” messages These are warnings, not errors — n8n still installs. Deprecated package warnings from n8n’s dependencies (inflight, rimraf, glob, gauge) are cosmetic. If n8n starts after install, you can ignore them. If it fails, look for the actual npm error code line below the warnings.

*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:

Root cause Typical error message What it means
Node version mismatch npm ERR! engine Unsupported engine n8n requires Node 20.19 to 24.x (LTS 20 or 22 recommended).
Missing build tools gyp ERR! stack Error: Can't find Python executable node‑gyp needs Python 3 + C/C++ toolchain.
Permission problems EACCES: permission denied npm cannot write to a directory you don’t own.
Corrupted cache / lockfile npm ERR! Unexpected end of JSON input while parsing Cache or package-lock.json is out‑of‑date.
Network / registry issues npm ERR! network request failed Proxy, firewall, or npm registry throttling.
Peer dependency conflict (npm 7+) npm ERR! code ERESOLVE npm 7+ enforces strict peer deps. Use --legacy-peer-deps to bypass.
isolated-vm ABI mismatch npm error path .../isolated-vm + gyp failure n8n’s sandbox module won’t compile on Node 22+ or 25. Use Node LTS 20.
Windows file lock (EPERM) EPERM: operation not permitted, rmdir Antivirus or Windows file indexer is locking node_modules during install.
Stale registry metadata (ETARGET) npm error code ETARGET — No matching version for @n8n/config npm’s local cache has a stale package manifest. Clear cache and retry.

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)

OS Command
macOS / Linux (nvm) 
nvm install 20 && nvm use 20
Windows (nvm‑windows) 
nvm install 20.19.0
nvm use 20.19.0
Apple Silicon / M1 / M2 Mac 
# 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
No version manager Download the LTS installer from https://nodejs.org and reinstall.

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)

Method When to use Command
npx n8n (no install) Quick test, CI pipelines npx n8n
Yarn (fallback) npm lockfile corrupted, Yarn deterministic installs yarn install –production
Docker (isolated environment) Persistent npm failures, need OS‑level isolation See page Docker installation errors for n8n
Manual binary (pre‑built) Edge‑case CI runners without build tools 
curl -L https://github.com/n8n-io/n8n/releases/download/<version>/n8n-linux-x64.tar.gz | tar -xz && ./n8n

7. Advanced troubleshooting checklist

Steps Checklist item How to verify
1 Node version is 20.19–24.x (prefer 20 LTS) node -v
2 npm version ≥ 10.0 (newer resolves many lockfile bugs) npm -v
3 Cache cleaned npm cache verify (should show 0 entries)
4 Build tools installed (gcc, make, python3) gcc –version / python3 –version
5 Permissions point to user‑owned directory npm config get prefix → should be under $HOME
6 Network can reach registry (curl https://registry.npmjs.org/npm) HTTP 200 response
7 Environment variable npm_config_python points to correct Python echo $npm_config_python
8 Optional deps (e.g., libsqlite3-dev) present dpkg -l | grep sqlite3 (Debian)
9 Lockfile matches package.json (npm ci succeeds) Run npm ci – should exit 0
10 No lingering processes locking files (lsof | grep package-lock.json) No output
11 ERESOLVE — tried --legacy-peer-deps npm install -g n8n –legacy-peer-deps
12 isolated-vm — Node version is not 25 or unstable node -v → must be 20.x or 22.x
13 Apple Silicon — Xcode CLI tools installed, node arch is arm64 node -e “console.log(process.arch)” → arm64

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.

Must Read

Leave a Comment

Your email address will not be published. Required fields are marked *