Run n8n Locally on Windows: Docker & Node.js Guide (2025 Update)

Run n8n Locally on Windows: Docker & Node.js Guide

Run n8n Locally on Windows: Docker & Node.js Guide (2025 Update)

Your complete walkthrough for setting up n8n on Windows using Docker (recommended) or Node.js as a reliable alternative. Includes persistent data and background operation!

Hello Automation Enthusiasts! 👋

Looking to run n8n, the powerful workflow automation tool, directly on your Windows machine? A local n8n setup is fantastic for development, testing new integrations, or managing personal automations with full control and privacy.

This guide will primarily focus on using Docker with WSL 2, the recommended approach for a stable and isolated n8n environment. However, we know that sometimes WSL 2 setup can hit a snag with BIOS virtualization settings. If that's you, don't worry! We've got you covered with a detailed Node.js alternative.

Let's get your local n8n instance up and running!

Why Docker for n8n on Windows?

  • Isolation: Docker containers package n8n and its dependencies, avoiding conflicts with other software on your system.
  • Consistency: What works in your local Docker container will work similarly elsewhere if you ever deploy it.
  • Background Operation: Easily run n8n as a background service.
  • Easy Updates: Updating n8n is often as simple as pulling a new Docker image.

Method 1: Docker with WSL 2 (Highly Recommended)

Prerequisites for Docker/WSL 2:

  • Windows 10 or 11 (64-bit)
  • Administrator Privileges on your PC
  • Hardware Virtualization Enabled in your PC's BIOS/UEFI (Key for WSL 2! Look for "Intel VT-x," "AMD-V," or similar).
  • A Docker Account (free to create at Docker Hub) for Docker Desktop.

Step 1: Install Docker Desktop & Initial Windows Setup

  1. Download Docker Desktop: Visit the official Docker website, log in, and download the installer for Windows.
  2. Install Docker Desktop: Run the installer. Follow the prompts. If asked, ensure "Use WSL 2 instead of Hyper-V" is selected (usually default).
  3. Restart Your Computer: ⚠️ Crucial! After installation, restart your Windows PC to finalize the setup.
  4. WSL 2 Basic Check (Post-Restart): Docker Desktop typically handles WSL 2. If Docker Desktop struggles to start or you see WSL errors, try this in an Administrator PowerShell: 
    PS> wsl --update # Updates WSL components
    If the kernel updated, you might run wsl --shutdown (WSL will restart when needed). Ensure "Virtual Machine Platform" and "Windows Subsystem for Linux" are enabled in "Turn Windows features on or off" (search in Start Menu).
    If you continue to see errors specifically stating "virtualization is not enabled in the BIOS" or mentioning HCS_E_HYPERV_NOT_INSTALLED despite "Virtual Machine Platform" being on, this points to a BIOS setting. See the "Troubleshooting WSL 2 & The BIOS Hurdle" section below.

Step 2: Understanding Data Persistence with Docker

To save your n8n workflows, credentials, and settings, we'll map a folder on your Windows PC to a folder inside the Docker container. The command we'll use specifies ${env:USERPROFILE}\.n8n. If this folder doesn't exist on your Windows machine, Docker will typically create it for you when the container starts. This folder (e.g., C:\Users\YourUserName\.n8n) will hold all your n8n data.

Step 3: Launching n8n with Docker (Background & Persistent)

  1. (Optional) Clean Up Old/Conflicting n8n Containers:
    If you've tried running an "n8n" container before and want a fresh start, or if you encounter a "name is already in use" error, open PowerShell as Administrator and run:

    PS> docker stop n8n
PS> docker rm n8n

    It's okay if these commands say "No such container."

  2. Execute the Docker Run Command:
    In PowerShell (as Administrator), copy and paste the following command:

    PS> docker run -d `
  --name n8n `
  -p 5678:5678 `
  -e N8N_RUNNERS_ENABLED=true `
  -v ${env:USERPROFILE}\.n8n:/home/node/.n8n `
  docker.n8n.io/n8nio/n8n:latest
    Understanding the Command:
    -d
    Detached Mode. Runs n8n in the background.
    --name n8n
    Assigns the name "n8n" for easy management.
    -p 5678:5678
    Maps port 5678 on your PC to port 5678 in the n8n container.
    -e N8N_RUNNERS_ENABLED=true
    Enables an n8n feature for separate workflow execution runners.
    -v ${env:USERPROFILE}\.n8n:/home/node/.n8n
    Persistent Data Volume! Links ${env:USERPROFILE}\.n8n on your Windows PC (e.g., C:\Users\YourUserName\.n8n) to /home/node/.n8n inside the container.
    docker.n8n.io/n8nio/n8n:latest
    The official latest n8n image.

    After this command, n8n is running! You don't need to go to Docker Desktop's "Images" section and click "Run" again.

Step 4: Accessing Your Local n8n (Docker Method)

  1. Give n8n a minute to initialize.
  2. Open your web browser and go to: http://localhost:5678
  3. Set up your n8n owner account. Your data will be saved in ${env:USERPROFILE}\.n8n.

Step 5: Managing Your Background n8n Container (Docker)

Use PowerShell for these:

  • Stop n8n: 
    docker stop n8n
  • Start n8n (existing): 
    docker start n8n
  • View Logs: 
    docker logs n8n
    (or 
    docker logs -f n8n
    for live logs)

Troubleshooting WSL 2 & The BIOS Hurdle

If wsl --update in Step 1 (Docker Method) didn't resolve issues and you're seeing errors like:

WSL2 is not supported with your current machine configuration.
Please enable the "Virtual Machine Platform" optional component and ensure virtualization is enabled in the BIOS...
Error code: Wsl/InstallDistro/Service/RegisterDistro/CreateVm/HCS/HCS_E_HYPERV_NOT_INSTALLED

This means:

  1. "Virtual Machine Platform" Windows feature might still be off (check "Turn Windows features on or off" in Start Menu). Enable it and restart.
  2. More critically, Hardware Virtualization is likely disabled in your computer's BIOS/UEFI.

Enabling virtualization in the BIOS involves restarting your PC and pressing a specific key (like F2, F10, Del, Esc – varies by manufacturer) during boot to enter the BIOS setup utility. The setting is often called "Intel Virtualization Technology (VT-x)," "AMD-V," or "SVM Mode" and needs to be set to "Enabled." Save changes and exit BIOS.

If modifying BIOS settings is something you're not comfortable with, or if your machine's BIOS is locked down, the Docker/WSL 2 method might be a roadblock. In this case, running n8n with Node.js is an excellent alternative!

Method 2: Node.js (Alternative if BIOS/WSL2 is Problematic)

If Docker/WSL2 isn't feasible due to BIOS/virtualization issues, you can run n8n directly using Node.js.

Step 1: Check for or Install Node.js

  1. Check Existing Installation: Open PowerShell and type:

    PS> node -v
PS> npm -v

    If these commands output version numbers (e.g., v20.11.0, 10.2.4), Node.js and npm are installed. Ensure your Node.js version is compatible (v18, v20, or v22 are generally good).

  2. Install Node.js (If Needed):

    • Go to the official Node.js website.
    • Download the LTS (Long Term Support) version for Windows.
    • Run the installer. Default options are usually fine. Ensure "Add to PATH" is selected.
    • After installation, close and reopen PowerShell, then re-verify with node -v and npm -v.

Step 2: Configure PowerShell Execution Policy

To allow npx to execute packages, you might need to adjust PowerShell's execution policy. This is a one-time setup for your current user.

  1. Open PowerShell as Administrator.

  2. Run the following command:

    PS> Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
    Set-ExecutionPolicy RemoteSigned
    Allows local scripts and signed internet scripts.
    -Scope CurrentUser
    Applies only to your user account.
    -Force
    Suppresses confirmation.

Step 3: Run n8n using npx

npx executes Node.js packages without global installation (or uses a global one if found).

  1. Open PowerShell (doesn't strictly need to be Admin for this step).

  2. Type the following command and press Enter:

    PS> npx n8n

  3. What Happens:

    • npx looks for the n8n package.
    • If it's the first time, it might ask for confirmation to download and run the latest n8n. Type y and press Enter if prompted.
    • n8n will start. You'll see log output in PowerShell.
    • By default, n8n data is stored in .n8n in your user profile (e.g., C:\Users\YourUserName\.n8n).

Step 4: Accessing Your Local n8n (Node.js Method)

  1. Once PowerShell shows n8n has started (e.g., "Editor is now available on port 5678"), open your web browser.
  2. Navigate to: http://localhost:5678
  3. Set up your n8n owner account.

Step 5: Stopping n8n (When Run via npx)

  • Go to the PowerShell window where n8n is running.
  • Press Ctrl+C. You might need to confirm termination.

Conclusion

Whether you choose the robust Docker/WSL 2 method or the straightforward Node.js approach, running n8n locally on Windows opens up a world of automation possibilities. If you hit the WSL 2 virtualization roadblock, remember the Node.js method is a solid and reliable alternative.

Happy Automating! 🚀

Comments

Post a Comment