{
  "schema_version": 2,
  "id": "integrate/bullmq",
  "title": "Redis with BullMQ",
  "url": "https://redis.io/docs/latest/integrate/bullmq/",
  "summary": "Run Node.js background jobs with BullMQ and Redis.",
  "tags": [
    "docs",
    "integrate",
    "oss",
    "rs",
    "rc"
  ],
  "last_updated": "2026-11-17T15:15:32Z",
  "children": [],
  "page_type": "content",
  "content_hash": "288336f865fa4dad15c943977d533ba446d93aeaf0d3ef09fc52c91f66af944f",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "[BullMQ](https://docs.bullmq.io/) is a job queue for Node.js (and other languages) that\nstores its queues in Redis. A `Queue` adds jobs, a `Worker` processes them, and\n`QueueEvents` reports what happened. See the\n[job queue use case](https://redis.io/docs/latest/develop/use-cases/job-queue) for when to\nchoose this pattern."
    },
    {
      "id": "requirements",
      "title": "Requirements",
      "role": "content",
      "text": "The examples on this page were run with BullMQ 6.7 and Node.js 23 against Redis 7.2.\nBullMQ checks the server version at startup. It requires Redis 5.0 or later and recommends\n6.2 or later.\n\nBullMQ 6 doesn't install a Redis client for you. Install it with\n[ioredis](https://redis.io/docs/latest/develop/clients/ioredis), or with\n[node-redis](https://redis.io/docs/latest/develop/clients/nodejs) as described\n[below](#use-node-redis):\n\n[code example]\n\nYou also need a running Redis server. You can run one locally with\n[Redis Open Source](https://redis.io/docs/latest/operate/oss_and_stack/install/archive/install-redis),\nuse [Docker](https://hub.docker.com/_/redis), or connect to\n[Redis Cloud](https://redis.io/cloud/)."
    },
    {
      "id": "add-and-process-jobs",
      "title": "Add and process jobs",
      "role": "content",
      "text": "Create a `Queue` and add jobs to it. Create a `Worker` with the same queue name and a\nfunction that processes each job. Both take a `connection` that points at Redis:\n\n[code example]"
    },
    {
      "id": "retry-delay-and-repeat-jobs",
      "title": "Retry, delay, and repeat jobs",
      "role": "content",
      "text": "Pass options when you add a job. This example retries a job up to 3 times with exponential\nbackoff, delays another by one second, and gives a third a high priority. A job\nscheduler adds a job on a repeating schedule:\n\n[code example]\n\nIn a test run, a job that threw an error on its first two attempts completed on the third,\nand the `digest` scheduler produced a new job about every 700 milliseconds."
    },
    {
      "id": "what-bullmq-stores-in-redis",
      "title": "What BullMQ stores in Redis",
      "role": "content",
      "text": "BullMQ stores everything under the prefix `bull:<queue-name>:`:\n\n| Key | Type | Contents |\n|-----|------|----------|\n| `bull:emails:<job-id>` | hash | The job: `name`, `data`, `opts`, `timestamp`, and `returnvalue` and `finishedOn` once it finishes. |\n| `bull:emails:completed` | sorted set | The IDs of completed jobs. |\n| `bull:emails:delayed` | sorted set | The IDs of delayed jobs, scored by the time they become ready. |\n| `bull:emails:id` | string | The counter that assigns job IDs. |\n| `bull:emails:repeat:<scheduler-id>` | | The state for each job scheduler. |\n\nWaiting jobs are stored in a list, `bull:emails:wait`, which exists only while it holds\njobs. Completed jobs stay in Redis until you remove them, so set `removeOnComplete` and\n`removeOnFail` on your jobs or workers to stop them accumulating."
    },
    {
      "id": "use-node-redis",
      "title": "Use node-redis",
      "role": "content",
      "text": "BullMQ uses ioredis by default. BullMQ 6 can use the\n[node-redis](https://redis.io/docs/latest/develop/clients/nodejs) client instead, through a factory\nthat you set once, before you create any queues or workers. Install node-redis 5 or later\n(`npm install bullmq redis`) and register the factory:\n\n[code example]\n\nA queue and worker created after this call completed a job in a test run. The factory is\na static setting, so it applies to every BullMQ connection in the process."
    },
    {
      "id": "more-information",
      "title": "More information",
      "role": "content",
      "text": "- [BullMQ documentation](https://docs.bullmq.io/)\n- [BullMQ on GitHub](https://github.com/taskforcesh/bullmq)"
    }
  ],
  "examples": [
    {
      "id": "requirements-ex0",
      "language": "bash",
      "code": "npm install bullmq ioredis",
      "section_id": "requirements"
    },
    {
      "id": "add-and-process-jobs-ex0",
      "language": "js",
      "code": "import { Queue, Worker, QueueEvents } from 'bullmq';\n\nconst connection = { host: '<your-redis-host>', port: 6379 };\n\nconst queue = new Queue('emails', { connection });\n\nconst worker = new Worker('emails', async (job) => {\n  return { sent: job.data.to };\n}, { connection, concurrency: 5 });\n\nconst events = new QueueEvents('emails', { connection });\nevents.on('completed', ({ jobId, returnvalue }) => {\n  console.log(`completed ${jobId}`, returnvalue);\n});\n\nawait queue.add('welcome', { to: 'a@example.com' });",
      "section_id": "add-and-process-jobs"
    },
    {
      "id": "retry-delay-and-repeat-jobs-ex0",
      "language": "js",
      "code": "await queue.add('flaky', { to: 'b@example.com' },\n  { attempts: 3, backoff: { type: 'exponential', delay: 200 } });\n\nawait queue.add('later', { to: 'c@example.com' }, { delay: 1000 });\n\nawait queue.add('urgent', { to: 'd@example.com' }, { priority: 1 });\n\nawait queue.upsertJobScheduler('digest', { every: 700 },\n  { name: 'digest', data: { to: 'all' } });",
      "section_id": "retry-delay-and-repeat-jobs"
    },
    {
      "id": "use-node-redis-ex0",
      "language": "js",
      "code": "import { RedisConnection, createNodeRedisClient } from 'bullmq';\nimport { createClient } from 'redis';\n\nRedisConnection.clientFactory = (opts) => {\n  const raw = createClient({ url: `redis://${opts.host ?? '127.0.0.1'}:${opts.port ?? 6379}` });\n  return createNodeRedisClient(raw);\n};",
      "section_id": "use-node-redis"
    }
  ]
}
