n8n Queue Mode Explained: Redis, Workers and When to Switch

n8n queue mode is the scaling setup in which the main n8n instance only receives triggers and webhooks and places each execution as a job in a Redis queue, while separate worker processes pick up those jobs, run them and write the results to PostgreSQL. You enable it by setting EXECUTIONS_MODE=queue on the main instance and every worker, pointing all of them at the same Redis and the same database, sharing one N8N_ENCRYPTION_KEY, and starting workers with n8n worker.

Regular mode vs queue mode

In regular mode a single n8n process does everything: it serves the editor and API, listens for webhooks, fires schedules and runs every execution. That is simple and works well for many instances. Its limits show when load grows:

• All executions share one Node.js process, which leans heavily on one CPU core.

• A heavy execution can slow the editor and webhook responses for everyone else.

• You cannot add capacity by adding processes or machines.

Queue mode separates receiving work from doing it. The main instance stays responsive, and throughput grows by adding workers. If you are still deciding whether you need it at all, our guide to n8n RAM and CPU requirements explains which signs point to a bigger server and which point to queue mode.

How the architecture fits together

• Main instance: runs the editor UI and REST API, registers webhooks, fires Schedule and polling triggers, and pushes execution jobs into Redis.

• Redis: the message broker. It holds the queue of pending jobs; it does not store your workflows or results.

• Workers: n8n processes started with n8n worker. Each one takes jobs from Redis, loads the workflow from the database, runs it and saves the execution.

• PostgreSQL: the shared source of truth for workflows, credentials and execution history. Every process connects to it.

• Webhook processors (optional): extra processes started with n8n webhook that only accept production webhook calls and enqueue them, for very high inbound volume.

A typical run: a webhook hits the main instance, the main instance creates a job in Redis, a free worker picks it up within moments, executes the workflow and writes the result to PostgreSQL, and the execution appears in the editor like any other.

The environment variables that matter

• EXECUTIONS_MODE=queue on the main instance and on every worker.

• QUEUE_BULL_REDIS_HOST, QUEUE_BULL_REDIS_PORT and QUEUE_BULL_REDIS_PASSWORD so every process reaches the same Redis.

• DB_TYPE=postgresdb plus the DB_POSTGRESDB_* variables, identical everywhere.

• N8N_ENCRYPTION_KEY, identical everywhere. Workers decrypt credentials with it; a mismatch means every workflow that uses credentials fails on the worker.

• QUEUE_HEALTH_CHECK_ACTIVE=true to expose a health endpoint on workers for monitoring.

• OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS=true to send manual test runs from the editor to workers as well; otherwise they run on the main instance. The default here has changed between versions.

Worker concurrency is set per process with the --concurrency flag, for example n8n worker --concurrency=5. It defaults to 10 in current releases. Names and defaults do change over time, so check the queue mode page in the n8n docs and the release notes for your version.

A sample Docker Compose setup

This runs PostgreSQL, Redis, one main instance and a scalable worker service on one server. Put a reverse proxy with TLS in front of port 5678, as described in our n8n self-hosting production guide.

services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: n8n
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: n8n
    volumes:
      - pg_data:/var/lib/postgresql/data

  redis:
    image: redis:7
    restart: unless-stopped
    command: ["redis-server", "--requirepass", "${REDIS_PASSWORD}"]
    volumes:
      - redis_data:/data

  n8n:
    image: docker.n8n.io/n8nio/n8n:${N8N_VERSION}
    restart: unless-stopped
    environment: &n8n-env
      DB_TYPE: postgresdb
      DB_POSTGRESDB_HOST: postgres
      DB_POSTGRESDB_DATABASE: n8n
      DB_POSTGRESDB_USER: n8n
      DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}
      EXECUTIONS_MODE: queue
      QUEUE_BULL_REDIS_HOST: redis
      QUEUE_BULL_REDIS_PORT: "6379"
      QUEUE_BULL_REDIS_PASSWORD: ${REDIS_PASSWORD}
      QUEUE_HEALTH_CHECK_ACTIVE: "true"
      N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}
      OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS: "true"
      GENERIC_TIMEZONE: Africa/Cairo
      N8N_HOST: n8n.example.com
      N8N_PROTOCOL: https
      WEBHOOK_URL: https://n8n.example.com/
    ports:
      - "127.0.0.1:5678:5678"
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on: [postgres, redis]

  n8n-worker:
    image: docker.n8n.io/n8nio/n8n:${N8N_VERSION}
    restart: unless-stopped
    command: worker --concurrency=5
    environment: *n8n-env
    depends_on: [n8n]

volumes:
  pg_data:
  redis_data:
  n8n_data:

# .env (keep it out of version control)
N8N_VERSION=x.y.z            # pin the exact release you tested
POSTGRES_PASSWORD=...
REDIS_PASSWORD=...
N8N_ENCRYPTION_KEY=...       # generate once: openssl rand -hex 32

The YAML anchor gives the worker exactly the same environment as the main instance, which removes the most common source of mismatched settings. Start it and scale workers with:

docker compose up -d
docker compose up -d --scale n8n-worker=3   # three worker containers
docker compose logs -f n8n-worker

Redis and PostgreSQL are not published to the internet here; they are reachable only on the internal Docker network. Our Docker Compose production checklist covers restart policies, logging and updates for stacks like this.

Optional: dedicated webhook processors

If inbound webhooks dominate your load, run one or more processes with n8n webhook using the same environment, and configure your reverse proxy to send /webhook/ paths to them and everything else to the main instance. Set N8N_DISABLE_PRODUCTION_MAIN_PROCESS=true on the main instance so it stops handling production webhooks itself. Test webhooks under /webhook-test/ still go to the main instance, because they belong to the editor session.

When to switch to queue mode

• One CPU core sits at 100% during busy periods while other cores stay idle.

• The editor becomes sluggish whenever large workflows run.

• Webhook bursts cause timeouts or slow responses.

• Long-running executions, such as AI agents waiting on model APIs, block shorter ones.

• You want to restart or update execution capacity without taking the editor down.

If none of these apply, regular mode with PostgreSQL and a sensible concurrency limit is simpler to operate.

Common pitfalls

• Different encryption keys. If a worker generates its own key, credentials cannot be decrypted. Set N8N_ENCRYPTION_KEY explicitly on every process and back it up.

• SQLite. Queue mode needs a database that all processes can share safely; use PostgreSQL.

• Binary data on the local filesystem. The n8n docs state that filesystem binary data mode is not supported in queue mode, because a file written by one process may not be visible to another. Use the storage option your version documents for queue mode, such as S3-compatible external storage.

• Version drift. The main instance and all workers must run the same n8n version. Update them together.

• Community nodes. Nodes installed through the editor must also be available to workers, or executions using them fail there.

• Exposed Redis. Never publish port 6379 to the internet, and always set a password.

• Wrong webhook URL. Behind a proxy, set WEBHOOK_URL so n8n generates public URLs with your domain and HTTPS.

Monitoring the queue

Watch two things: worker CPU and memory, and the number of jobs waiting. A steadily growing backlog means you need more workers or higher concurrency; idle workers and an empty queue mean you have headroom. With n8n's default queue prefix, you can read the backlog straight from Redis:

docker compose exec redis redis-cli -a "$REDIS_PASSWORD" LLEN bull:jobs:wait

Key names can differ between versions. n8n can also expose Prometheus metrics with N8N_METRICS=true, including queue metrics in recent releases.

Frequently asked questions

Does n8n queue mode require Redis?

Yes. Redis is the broker that passes jobs from the main instance to the workers. PostgreSQL is also needed as the shared database.

Can workers run on the same server as the main instance?

Yes, and on a single server that is the usual setup. Workers can also run on other machines as long as they can reach Redis and PostgreSQL securely.

How many workers should I start with?

Start with one or two workers at a moderate concurrency such as 5, then scale based on CPU use and queue backlog during your busiest hours.

Is queue mode a paid feature?

Queue mode is available in self-hosted n8n. Running several main instances for high availability (multi-main) is a separate feature tied to n8n's enterprise licensing.

Queue mode on IM HOST n8n Hosting

IM HOST n8n Hosting includes queue mode with Redis workers on the Pro plan and above, on a dedicated NVMe KVM server with the latest n8n and PostgreSQL installed for you. You get full root to tune worker concurrency, free daily backups and unlimited workflows and executions. Servers run in Germany, Poland, the UK, the USA and Egypt; current stock is listed on the data centers page.