Install n8n Locally: Quick Setup Guide

n8n is an open-source workflow automation platform you can install and run on your own machine. To install n8n locally, you need Docker or Node.js, then run either a one-line setup or a multi-step Docker Compose deployment. Installation takes 5-15 minutes, and you'll have full access to n8n's interface on port 5678. This guide walks you through every installation method, common pitfalls, and how to verify your setup works.

What Is Local n8n Installation, and Should You Do It?

Local n8n installation means running n8n on your own computer or internal server instead of using n8n Cloud. You control the data, the infrastructure, and the customizations. The trade-off is you manage the server, backups, and updates yourself.

Why choose local? Cost is the first reason. n8n Cloud starts at $300/month for a team plan; local installation is free. Control comes second. Your workflows and credentials stay on your machine. Customization comes third. You can modify the source code, add custom nodes, or integrate with your private network without cloud restrictions.

Local n8n suits small teams (under 20 people), development environments, and companies with strict data residency rules. If your team is 100+ people or you need 99.9% uptime guarantees, managed n8n hosting (like what Opsily offers) is more reliable and less overhead. This tutorial covers the self-hosted path.

System Requirements and Prerequisites

Before you install, check these requirements:

• Operating System: macOS, Windows (with WSL 2), or Linux. Windows 11/10 with WSL 2 enabled is supported; bare Windows PowerShell is not.
• RAM: Minimum 2GB, but 4GB or more is recommended for workflows with multiple integrations.
• CPU: Any modern processor works; no special chips required.
• Disk Space: At least 1GB free.
• Internet Connection: Required during setup to download Docker or Node.js, and to fetch npm packages if using npm installation.

Dependencies: You'll need either Docker + Docker Desktop or Node.js 18+. Docker is recommended for ease. If you go the npm route, you also need PostgreSQL or another database for persistence (the default SQLite is limited for production).

Port Availability: n8n runs on port 5678 by default. Check that port 5678 is not in use on your machine. On Linux or macOS, run lsof -i :5678 to check. On Windows, use netstat -ano | findstr :5678.

Installation Method Overview

n8n offers three main local installation paths:

1. One-Line Docker Setup (Fastest): A single command starts n8n in a container. Data is lost when the container stops. Best for testing and learning.

2. Docker Compose (Most Robust): A configuration file runs n8n, PostgreSQL, and Redis in containers. Data persists on disk. Best for long-term local use.

3. npm Installation (Deprecated): Install via Node.js package manager. Requires manual database setup. Deprecated in n8n 3.0; avoid this unless you have legacy workflows.

Docker is standard now. The npm path is discouraged. Choose one-line if you're testing. Choose Docker Compose if you plan to keep n8n running and don't want data loss.

Installation Method 1: The One-Line Docker Setup (Recommended for Testing)

This is the fastest way to try n8n locally. One command, and n8n runs in Docker.

Step 1: Install Docker Desktop

1. Go to the Docker Desktop download page.
2. Download Docker Desktop for your OS (Windows, macOS, or Linux).
3. Install and start Docker Desktop.
4. Verify installation: Open Terminal or PowerShell and run docker --version. You should see "Docker version 25.x.x" or similar.

Step 2: Run the One-Line Setup

Open Terminal (macOS/Linux) or PowerShell (Windows) and run:

docker run -it --rm --name n8n -p 5678:5678 n8n

This command downloads the latest n8n Docker image, starts a container named "n8n" that runs n8n, and maps port 5678 inside the container to port 5678 on your computer. The --rm flag deletes the container when it stops (and all data is lost). The -it flag keeps the terminal connected so you see logs in real-time.

Wait 30-60 seconds for n8n to start. You'll see messages about the database initializing and the server starting.

Step 3: Access n8n

1. Open your browser.
2. Visit localhost:5678
3. You'll see the n8n login page. Create an admin account.
4. Click "Next" and set a password.
5. You're in. Create your first workflow.

Step 4: Stop n8n

Press Ctrl+C in the terminal. The container stops and all data is erased. This is fine for testing. If you want persistent storage, use Docker Compose instead.

Installation Method 2: Docker Compose for Production-Like Setup

Docker Compose runs n8n with PostgreSQL (for data persistence) and Redis (for job queueing) in a coordinated setup. Data survives restarts. This is the production-standard local setup.

Step 1: Install Docker Desktop

Follow the steps in "Installation Method 1: Step 1" above.

Step 2: Create a Directory and docker-compose.yml File

1. Create a new folder for n8n. Example: mkdir ~/n8n-local.
2. Navigate into it: cd ~/n8n-local.
3. Create a file named docker-compose.yml (note the dot in the filename).
4. Copy this content into the file:

version: '3.8'

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: n8n
      POSTGRES_PASSWORD: n8n_password_123
      POSTGRES_DB: n8n
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - n8n_network

  n8n:
    image: n8nio/n8n:latest
    ports:
      - "5678:5678"
    environment:
      DB_TYPE: postgresdb
      DB_POSTGRESDB_HOST: postgres
      DB_POSTGRESDB_PORT: 5432
      DB_POSTGRESDB_DATABASE: n8n
      DB_POSTGRESDB_USER: n8n
      DB_POSTGRESDB_PASSWORD: n8n_password_123
      N8N_BASIC_AUTH_ACTIVE: 'true'
      N8N_BASIC_AUTH_USER: admin
      N8N_BASIC_AUTH_PASSWORD: n8n_password_123
    depends_on:
      - postgres
    volumes:
      - n8n_data:/home/node/.n8n
    networks:
      - n8n_network

volumes:
  postgres_data:
  n8n_data:

networks:
  n8n_network:
    driver: bridge

This configuration runs PostgreSQL in one container and n8n in another, sets environment variables for database connection, and stores data in Docker volumes (postgres_data and n8n_data) so it persists after shutdown. The configuration uses basic auth (username: admin, password: n8n_password_123). Change this before production use.

Step 3: Start the Services

In the terminal, inside the ~/n8n-local directory, run:

docker-compose up -d

The -d flag runs in the background (detached mode). Wait 10-20 seconds for PostgreSQL and n8n to start.

Step 4: Verify the Deployment

Check that both services are running:

docker-compose ps

You should see two containers: postgres and n8n, both with status "Up".

Step 5: Access n8n

Visit localhost:5678 in your browser. Log in with username admin and password n8n_password_123.

Step 6: Stopping and Restarting

To stop: docker-compose down (data persists in volumes). To start again: docker-compose up -d. To view logs: docker-compose logs -f n8n.

Installation Method 3: npm Installation (Deprecated from n8n 3.0)

The npm method is no longer recommended. n8n's official documentation marks it as deprecated starting with version 3.0. Use Docker instead.

If you have legacy workflows or specific reasons to use npm, install Node.js 18+, then run:

npm install -g n8n
n8n

You'll need a PostgreSQL database running separately. This adds complexity. Docker Compose handles it automatically, so it's the better choice for local setups.

Accessing n8n and Verifying Installation

Once n8n is running, visit localhost:5678 in your browser. You'll see the login or setup page.

First-Time Setup:

1. Create an admin account with an email and password.
2. Click "Next" to confirm.
3. You're logged in to the n8n interface.

Verify Installation Works:

1. Click "Create Workflow" (or "New Workflow" depending on your version).
2. Click the "+" icon to add a node.
3. Select "Schedule" and set it to trigger every minute.
4. Add another node: "Manual Trigger" (or any node like "Send Email").
5. Connect the nodes by dragging from the output of one to the input of another.
6. Save and activate the workflow.
7. Check the execution log to confirm the workflow runs.

If you see the workflow execute, congratulations: your n8n installation works. You're ready to build real workflows.

Troubleshooting Common Installation Issues

Issue 1: Port 5678 is already in use

Solution: Change the port in your command or docker-compose.yml. For one-line setup, use:

docker run -it --rm -p 8080:5678 n8n

Then visit localhost:8080. For Docker Compose, change the ports line to - "8080:5678".

Issue 2: Docker is not running on macOS or Windows

Solution: Open Docker Desktop. Wait for the Docker icon to stop animating (30 seconds). Then retry your docker command.

Issue 3: Connection refused when accessing localhost on port 5678

Solution: Confirm n8n is fully started. Run docker ps to see if the container is still running. If it exited, check logs with docker logs n8n. Common causes: insufficient RAM, port conflict, or missing Docker.

Issue 4: Windows WSL 2 issues

Windows 10/11 with WSL 2 can have permission or networking issues. Ensure: WSL 2 is enabled (check in Settings > Apps > Apps & Features > Programs and Features > Turn Windows features on or off, and enable "Windows Subsystem for Linux"), Docker Desktop is set to use WSL 2 backend (Settings > Resources > WSL Integration), and restart Docker Desktop after enabling WSL 2.

Issue 5: Data disappears after restarting the container (one-line setup)

This is expected with --rm. The container is deleted on stop, taking data with it. This is fine for testing. Use Docker Compose instead to persist data.

Issue 6: Permission denied on Linux

You may need to run docker commands with sudo or add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Log out and back in for the group change to take effect.

Issue 7: Database connection errors (Docker Compose)

Verify PostgreSQL started: docker-compose ps. If postgres is down, check logs: docker-compose logs postgres. Common cause: port 5432 in use or invalid password in docker-compose.yml. Review pricing and managed hosting costs if you'd rather avoid infrastructure management.

Frequently Asked Questions

How do I install n8n locally on Windows?

Use Docker Desktop for Windows with WSL 2 enabled. Install Docker Desktop, enable WSL 2 in Windows Features, then run the docker command. Windows users often face WSL 2 configuration issues, so ensure it is enabled in Settings and Docker Desktop is configured to use the WSL 2 backend.

Is n8n free if run locally?

Yes. The n8n source code is open-source and free to use. You only pay for your hosting infrastructure (computer, server, or cloud instance). Hosting the instance itself costs nothing if it's on your machine; you pay for cloud infrastructure if you use a VPS or managed hosting.

Can I self-host n8n?

Yes. n8n is explicitly designed for self-hosting. The source code is on GitHub (203.3k stars). You can run it on your own hardware, a cloud VPS, or a managed hosting provider like Opsily.

How to install N8N via Docker Compose?

Create a docker-compose.yml file with PostgreSQL and n8n services, then run docker-compose up -d. See "Installation Method 2" above for the full configuration and steps. This method persists data across restarts and is the recommended approach for long-term local setups.

What is the cost of self-hosting n8n?

The software is free. Your costs depend on your infrastructure. Running on a laptop: $0. Running on a cloud VPS: $5-30/month depending on the provider. Running on managed hosting: typically $200-500/month for a managed service with backups and support. Explore your options at Opsily.

The Bottom Line

Local n8n installation takes 10 minutes with Docker and gives you full workflow automation control at zero software cost. Docker Compose is the standard choice for anything beyond testing. Once running, you access the interface on port 5678 and start building workflows.

If you outgrow a local setup and need reliability, backups, and team management, Opsily offers managed n8n hosting that handles infrastructure for you.