Run n8n on Windows the Right Way: Complete WSL2 Setup Guide

If you've tried running n8n natively on Windows and hit PowerShell quirks, path issues, or just want a proper Linux runtime without a VM, WSL2 is your answer. This guide walks you through a clean n8n Windows setup with WSL2 — from enabling the subsystem to running n8n as a persistent background service.

Prerequisites

Before diving in, make sure you have:

• Windows 10 (Build 19041+) or Windows 11
• Administrator access on your Windows machine
• At least 4 GB RAM (8 GB recommended)
• Basic comfort with terminal commands
• Virtualization enabled in BIOS (check Task Manager → Performance → CPU → Virtualization: Enabled)

Section 1: Enable WSL2 on Windows

WSL2 uses a real Linux kernel via a lightweight VM, giving you full compatibility with Node.js, npm, and n8n's dependencies.

Step 1: Install WSL2

Open PowerShell as Administrator and run:

wsl --install

This installs WSL2 and Ubuntu (the default distro) in one shot. Reboot when prompted.

Step 2: Verify WSL2 is the default version

wsl --set-default-version 2
wsl --list --verbose

You should see your Ubuntu distro listed with VERSION 2.

Step 3: Launch Ubuntu and create your user

Open the Ubuntu app from the Start menu (or run wsl in PowerShell). Set a username and password when prompted. This is your Linux user — keep it simple.

Section 2: Update Ubuntu and Install Node.js

n8n runs on Node.js. We'll use nvm (Node Version Manager) for a clean install that avoids permission headaches.

Update packages

sudo apt update && sudo apt upgrade -y

Install nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc

Install Node.js LTS

n8n requires Node.js 18 or 20. Use LTS for stability:

nvm install --lts
nvm use --lts
node -v   # should output v20.x.x or similar
npm -v

Section 3: Install n8n

With Node.js in place, installing n8n is a single command:

npm install -g n8n

Verify the install:

n8n --version

If you're planning to self-host n8n for production use or want to understand the broader architecture, check out our guide: How to Self-Host n8n: Build Unlimited AI Automation Workflows.

Section 4: Configure n8n and First Launch

Set environment variables

Create a config file so you're not exporting env vars manually every session:

# Add to ~/.bashrc or ~/.profile
export N8N_HOST=0.0.0.0
export N8N_PORT=5678
export N8N_PROTOCOL=http
export WEBHOOK_URL=http://localhost:5678/
export N8N_BASIC_AUTH_ACTIVE=true
export N8N_BASIC_AUTH_USER=admin
export N8N_BASIC_AUTH_PASSWORD=changeme123

Then reload:

source ~/.bashrc

Start n8n

n8n start

Open your browser on Windows and navigate to http://localhost:5678. You should see the n8n login screen.

Section 5: Run n8n as a Persistent Background Service

Running n8n in a terminal tab works for dev, but you'll want it to survive terminal closes and WSL restarts for real use.

Option A: Use pm2 (recommended)

pm2 is a Node.js process manager that handles auto-restart and logs:

npm install -g pm2
pm2 start n8n --name n8n-service
pm2 save
pm2 startup

The pm2 startup command will print a shell command — copy and run it to enable auto-start on WSL boot.

Option B: Use a Windows Task Scheduler trigger

If you want n8n to start when Windows boots (without manually launching WSL), create a Task Scheduler entry that runs:

wsl -d Ubuntu -- bash -c "source ~/.bashrc && pm2 resurrect"

Set the trigger to "At log on" and run with highest privileges.

Section 6: Tips, Gotchas & Troubleshooting

n8n command not found after install

This usually means nvm's shims aren't in your PATH. Run source ~/.bashrc and try again. If it persists, check that nvm's init block is in your ~/.bashrc:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

Port 5678 already in use

lsof -i :5678
kill -9 <PID>

WSL2 loses network after Windows sleep

This is a known WSL2 bug. A quick fix: restart the WSL network adapter from an elevated PowerShell:

Get-NetAdapter | Where-Object {$_.InterfaceDescription -like "*WSL*"} | Restart-NetAdapter

Accessing n8n from other devices on your LAN

WSL2 runs on a NAT'd internal IP. To expose n8n to your local network, add a port proxy rule in Windows:

# Run in PowerShell as Administrator
# Replace 172.x.x.x with your WSL2 IP (run `hostname -I` inside WSL)
netsh interface portproxy add v4tov4 listenport=5678 listenaddress=0.0.0.0 connectport=5678 connectaddress=172.x.x.x

Keeping n8n updated

npm update -g n8n
pm2 restart n8n-service

General tips

• Store your n8n data in the Linux filesystem (/home/youruser/.n8n), not in /mnt/c/ — Windows-mounted paths are significantly slower.
• Use SQLite for local dev (the default). Switch to Postgres before going anywhere near production.
• Back up your workflows regularly via n8n's export feature: Settings → Import/Export.
• If you're running webhooks, consider a tool like ngrok to expose your local instance temporarily for testing.

What's Next

You now have a fully functional n8n Windows setup with WSL2 running as a persistent service. From here you can:

• Connect integrations (Slack, Gmail, HTTP APIs, databases)
• Build multi-step automation workflows with the visual editor
• Explore AI agent nodes for LLM-powered workflows
• Migrate to a VPS or Docker when you're ready for production — see our guide on self-hosting n8n for unlimited AI automation