> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/n8n-io/n8n/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation Guide

> Install and configure n8n for production use with npm, Docker, or Kubernetes

# Installation Guide

This guide covers different installation methods for n8n, from local development to production deployments. Choose the method that best fits your infrastructure and requirements.

<Note>
  **Requirements**:

  * Node.js 22.16+ (for npm installation)
  * Docker 20.10+ (for Docker installation)
  * PostgreSQL 13+ (recommended for production)
</Note>

## Installation Methods

<CardGroup cols={3}>
  <Card title="npm" icon="node-js">
    Best for local development and small deployments
  </Card>

  <Card title="Docker" icon="docker">
    Recommended for production and containerized environments
  </Card>

  <Card title="Kubernetes" icon="dharmachakra">
    Best for large-scale, highly available deployments
  </Card>
</CardGroup>

## npm Installation

### Global Installation

Install n8n globally using npm:

<Steps>
  <Step title="Install n8n">
    ```bash theme={null}
    npm install n8n -g
    ```
  </Step>

  <Step title="Start n8n">
    ```bash theme={null}
    n8n
    ```

    n8n will start and be accessible at [http://localhost:5678](http://localhost:5678)
  </Step>

  <Step title="Configure (Optional)">
    Set environment variables for your setup:

    ```bash theme={null}
    export N8N_BASIC_AUTH_ACTIVE=true
    export N8N_BASIC_AUTH_USER=admin
    export N8N_BASIC_AUTH_PASSWORD=secure_password
    n8n
    ```
  </Step>
</Steps>

### Quick Start (No Installation)

For trying n8n without installation:

```bash theme={null}
npx n8n
```

<Tip>
  Use `npx` for quick tests and demos. For production, use a proper installation method.
</Tip>

### Running Specific Commands

The n8n CLI supports multiple commands:

<CodeGroup>
  ```bash Start (Default) theme={null}
  # Start the main n8n instance
  n8n start

  # Or simply
  n8n
  ```

  ```bash Worker Mode theme={null}
  # Run as a worker instance (queue mode)
  n8n worker
  ```

  ```bash Webhook Mode   theme={null}
  # Run as webhook-only instance
  n8n webhook
  ```

  ```bash Execute Workflow theme={null}
  # Execute a workflow from command line
  n8n execute --id=<workflow_id>
  ```
</CodeGroup>

<Note>
  The n8n binary is located at `/packages/cli/bin/n8n` in the source code. It checks your Node.js version and loads the configuration before starting.
</Note>

## Docker Installation

### Basic Docker Setup

<Steps>
  <Step title="Create Data Volume">
    ```bash theme={null}
    docker volume create n8n_data
    ```
  </Step>

  <Step title="Run n8n Container">
    ```bash theme={null}
    docker run -d \
      --name n8n \
      -p 5678:5678 \
      -v n8n_data:/home/node/.n8n \
      docker.n8n.io/n8nio/n8n
    ```
  </Step>

  <Step title="Check Status">
    ```bash theme={null}
    docker ps
    docker logs n8n
    ```
  </Step>
</Steps>

### Docker Compose Setup

For production deployments, use Docker Compose:

```yaml docker-compose.yml theme={null}
version: '3.8'

services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: n8n
      POSTGRES_PASSWORD: n8n_password
      POSTGRES_DB: n8n
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U n8n']
      interval: 5s
      timeout: 5s
      retries: 10

  n8n:
    image: docker.n8n.io/n8nio/n8n
    restart: unless-stopped
    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
      - N8N_ENCRYPTION_KEY=your_encryption_key_here
      - N8N_WEBHOOK_URL=https://your-domain.com/
      - N8N_EDITOR_BASE_URL=https://your-domain.com/
      - GENERIC_TIMEZONE=America/New_York
      - N8N_LOG_LEVEL=info
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  postgres_data:
  n8n_data:
```

Deploy with:

```bash theme={null}
docker-compose up -d
```

<Warning>
  Always set a strong `N8N_ENCRYPTION_KEY` in production. This key encrypts sensitive data like credentials. If lost, you cannot decrypt existing credentials.
</Warning>

### Docker Compose with Queue Mode

For high-volume workflows, use queue mode with separate worker instances:

```yaml docker-compose-queue.yml theme={null}
version: '3.8'

services:
  redis:
    image: redis:7
    restart: unless-stopped
    volumes:
      - redis_data:/data
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 5s
      timeout: 5s
      retries: 10

  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: n8n
      POSTGRES_PASSWORD: n8n_password
      POSTGRES_DB: n8n
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U n8n']
      interval: 5s
      timeout: 5s
      retries: 10

  n8n-main:
    image: docker.n8n.io/n8nio/n8n
    restart: unless-stopped
    ports:
      - '5678:5678'
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=n8n_password
      - QUEUE_BULL_REDIS_HOST=redis
      - EXECUTIONS_MODE=queue
      - N8N_ENCRYPTION_KEY=your_encryption_key_here
      - N8N_WEBHOOK_URL=https://your-domain.com/
      - N8N_EDITOR_BASE_URL=https://your-domain.com/
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  n8n-worker:
    image: docker.n8n.io/n8nio/n8n
    restart: unless-stopped
    command: worker
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=n8n_password
      - QUEUE_BULL_REDIS_HOST=redis
      - EXECUTIONS_MODE=queue
      - N8N_ENCRYPTION_KEY=your_encryption_key_here
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    deploy:
      replicas: 2

volumes:
  redis_data:
  postgres_data:
  n8n_data:
```

<Note>
  Queue mode requires Redis and separates the main instance (UI + triggers) from worker instances (workflow execution). This allows horizontal scaling of workers.
</Note>

## Configuration

### Essential Environment Variables

n8n is highly configurable through environment variables:

#### Database Configuration

<CodeGroup>
  ```bash SQLite (Default) theme={null}
  # SQLite is used by default
  DB_TYPE=sqlite

  # Optional: Run VACUUM on startup
  DB_SQLITE_VACUUM_ON_STARTUP=true
  ```

  ```bash PostgreSQL (Recommended) theme={null}
  # PostgreSQL configuration
  DB_TYPE=postgresdb
  DB_POSTGRESDB_HOST=localhost
  DB_POSTGRESDB_PORT=5432
  DB_POSTGRESDB_DATABASE=n8n
  DB_POSTGRESDB_USER=n8n
  DB_POSTGRESDB_PASSWORD=secure_password
  DB_POSTGRESDB_SCHEMA=public
  ```
</CodeGroup>

<Warning>
  SQLite is not recommended for production use. Use PostgreSQL for better performance and reliability.
</Warning>

#### Security Configuration

```bash theme={null}
# Encryption key for credentials (REQUIRED for production)
N8N_ENCRYPTION_KEY=your_very_long_random_encryption_key

# JWT secret for authentication
N8N_JWT_SECRET=your_jwt_secret

# Basic auth (if not using user management)
N8N_BASIC_AUTH_ACTIVE=true
N8N_BASIC_AUTH_USER=admin
N8N_BASIC_AUTH_PASSWORD=secure_password
```

#### Webhook & URL Configuration

```bash theme={null}
# Public URL for webhooks
N8N_WEBHOOK_URL=https://your-domain.com/

# Editor/UI base URL
N8N_EDITOR_BASE_URL=https://your-domain.com/

# Path prefix (if behind reverse proxy)
N8N_PATH=/n8n/
```

#### Execution Configuration

```bash theme={null}
# Execution mode: regular or queue
EXECUTIONS_MODE=regular

# Queue mode settings (if using queue)
QUEUE_BULL_REDIS_HOST=localhost
QUEUE_BULL_REDIS_PORT=6379
QUEUE_BULL_REDIS_PASSWORD=redis_password

# Maximum concurrent executions
N8N_CONCURRENCY_PRODUCTION_LIMIT=10
```

#### Logging & Monitoring

```bash theme={null}
# Log level: error, warn, info, debug, verbose
N8N_LOG_LEVEL=info

# Log output: console, file
N8N_LOG_OUTPUT=console

# Timezone
GENERIC_TIMEZONE=America/New_York
```

<Tip>
  For a complete list of configuration options, see the n8n documentation or check `/packages/cli/src/config/` in the source code.
</Tip>

### Configuration File

Alternatively, use a configuration file:

```json config/default.json theme={null}
{
  "database": {
    "type": "postgresdb",
    "postgresdb": {
      "host": "localhost",
      "port": 5432,
      "database": "n8n",
      "user": "n8n",
      "password": "secure_password"
    }
  },
  "credentials": {
    "overwrite": {
      "data": "{}"
    }
  },
  "executions": {
    "mode": "regular",
    "timeout": 3600,
    "maxTimeout": 3600
  },
  "timezone": "America/New_York"
}
```

Place this file in the `~/.n8n/config/` directory or set `NODE_CONFIG_DIR` environment variable.

## Production Deployment

### Reverse Proxy Setup (nginx)

For production, put n8n behind a reverse proxy:

```nginx theme={null}
server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/ssl/certs/your-domain.crt;
    ssl_certificate_key /etc/ssl/private/your-domain.key;

    location / {
        proxy_pass http://localhost:5678;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        
        # Required for webhooks
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # Increase timeouts for long-running workflows
        proxy_connect_timeout 3600;
        proxy_send_timeout 3600;
        proxy_read_timeout 3600;
        send_timeout 3600;
    }
}
```

### Systemd Service

Create a systemd service for n8n:

```ini /etc/systemd/system/n8n.service theme={null}
[Unit]
Description=n8n - Workflow Automation Tool
After=network.target

[Service]
Type=simple
User=n8n
WorkingDirectory=/home/n8n
Environment="NODE_ENV=production"
Environment="N8N_ENCRYPTION_KEY=your_encryption_key"
Environment="DB_TYPE=postgresdb"
Environment="DB_POSTGRESDB_HOST=localhost"
Environment="DB_POSTGRESDB_DATABASE=n8n"
Environment="DB_POSTGRESDB_USER=n8n"
Environment="DB_POSTGRESDB_PASSWORD=secure_password"
Environment="N8N_WEBHOOK_URL=https://your-domain.com/"
Environment="N8N_EDITOR_BASE_URL=https://your-domain.com/"
ExecStart=/usr/local/bin/n8n start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

Enable and start:

```bash theme={null}
sudo systemctl enable n8n
sudo systemctl start n8n
sudo systemctl status n8n
```

## Building from Source

For development or custom builds:

<Steps>
  <Step title="Clone Repository">
    ```bash theme={null}
    git clone https://github.com/n8n-io/n8n.git
    cd n8n
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    # Requires pnpm 10.22.0+
    npm install -g pnpm
    pnpm install
    ```
  </Step>

  <Step title="Build All Packages">
    ```bash theme={null}
    pnpm build > build.log 2>&1
    ```

    <Note>
      Build output is redirected to avoid overwhelming the console. Check `build.log` for any errors.
    </Note>
  </Step>

  <Step title="Start Development">
    ```bash theme={null}
    # Start all services in dev mode
    pnpm dev

    # Or start only backend
    pnpm dev:be

    # Or start only frontend
    pnpm dev:fe
    ```
  </Step>
</Steps>

<Warning>
  n8n uses a monorepo structure with pnpm workspaces. Always use `pnpm` instead of `npm` or `yarn`.
</Warning>

## Advanced Configuration

### Multi-Main Setup (High Availability)

For enterprise deployments, enable multi-main mode:

```bash theme={null}
# Enable multi-main setup (requires Enterprise license)
EXECUTIONS_MODE=queue
N8N_MULTI_MAIN_SETUP_ENABLED=true
QUEUE_BULL_REDIS_HOST=redis_host
```

<Note>
  Multi-main setup requires:

  * Queue mode (Redis)
  * Enterprise license
  * PostgreSQL database
  * Multiple n8n main instances
</Note>

### External Secrets

Load sensitive values from external sources:

```bash theme={null}
# Use environment variables for secrets
export N8N_ENCRYPTION_KEY=$(cat /run/secrets/encryption_key)
export DB_POSTGRESDB_PASSWORD=$(cat /run/secrets/db_password)
```

### Custom Node Loading

Load custom nodes from a directory:

```bash theme={null}
N8N_CUSTOM_EXTENSIONS=/path/to/custom/nodes
```

## Upgrading n8n

### npm Upgrade

```bash theme={null}
npm install n8n@latest -g
```

### Docker Upgrade

```bash theme={null}
# Pull latest image
docker pull docker.n8n.io/n8nio/n8n:latest

# Restart container
docker-compose down
docker-compose up -d
```

<Warning>
  Always backup your database before upgrading. n8n runs database migrations automatically on startup.
</Warning>

## Backup & Recovery

### Backup Database

<CodeGroup>
  ```bash PostgreSQL theme={null}
  # Backup
  pg_dump -U n8n n8n > n8n_backup_$(date +%Y%m%d).sql

  # Restore
  psql -U n8n n8n < n8n_backup_20260219.sql
  ```

  ```bash SQLite theme={null}
  # Backup (copy database file)
  cp ~/.n8n/database.sqlite ~/.n8n/database.sqlite.backup

  # Restore
  cp ~/.n8n/database.sqlite.backup ~/.n8n/database.sqlite
  ```
</CodeGroup>

### Backup n8n Data Directory

```bash theme={null}
tar -czf n8n_data_backup_$(date +%Y%m%d).tar.gz ~/.n8n/
```

## Monitoring & Health Checks

### Health Check Endpoint

n8n exposes a health check endpoint:

```bash theme={null}
curl http://localhost:5678/healthz
```

### Metrics (Prometheus)

Enable Prometheus metrics:

```bash theme={null}
N8N_METRICS=true
N8N_METRICS_PORT=9090
```

Metrics are available at:

```
http://localhost:9090/metrics
```

## Troubleshooting

### Database Connection Issues

<Steps>
  <Step title="Check Database">
    ```bash theme={null}
    # PostgreSQL
    psql -U n8n -h localhost -d n8n

    # Check connection
    \conninfo
    ```
  </Step>

  <Step title="Verify Configuration">
    Check environment variables are set correctly:

    ```bash theme={null}
    echo $DB_TYPE
    echo $DB_POSTGRESDB_HOST
    ```
  </Step>

  <Step title="Check Logs">
    ```bash theme={null}
    # Docker
    docker logs n8n

    # Systemd
    journalctl -u n8n -f
    ```
  </Step>
</Steps>

### Performance Issues

* Use PostgreSQL instead of SQLite
* Enable queue mode for high-volume workflows
* Increase worker instances
* Configure execution timeouts appropriately
* Enable database connection pooling

### Permission Errors

```bash theme={null}
# Fix n8n data directory permissions
sudo chown -R $USER:$USER ~/.n8n/
chmod 700 ~/.n8n/
```

## Getting Help

<CardGroup cols={2}>
  <Card title="Community Forum" icon="comments" href="https://community.n8n.io">
    Get installation support from the community
  </Card>

  <Card title="Documentation" icon="book" href="https://docs.n8n.io">
    Detailed configuration documentation
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/n8n-io/n8n/issues">
    Report installation bugs
  </Card>

  <Card title="Enterprise Support" icon="headset" href="https://n8n.io/enterprise">
    Contact for enterprise installation support
  </Card>
</CardGroup>