{
  "schema_version": 2,
  "id": "integrate/rq",
  "title": "Redis with RQ",
  "url": "https://redis.io/docs/latest/integrate/rq/",
  "summary": "Run Python background jobs with RQ (Redis Queue).",
  "tags": [
    "docs",
    "integrate",
    "oss",
    "rs",
    "rc"
  ],
  "last_updated": "2026-11-17T16:15:21Z",
  "children": [],
  "page_type": "content",
  "content_hash": "41c2712246c2bf454dc49622f1e45260143a9b36203860012b6e3fcbbd8e0631",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "[RQ](https://python-rq.org/) (Redis Queue) is a Python library for queueing jobs and\nprocessing them in the background with workers. Redis is its only data store. RQ jobs are\nordinary Python functions, so there is no task decorator to add. See the\n[job queue use case](https://redis.io/docs/latest/develop/use-cases/job-queue) for when to choose\nthis pattern."
    },
    {
      "id": "requirements",
      "title": "Requirements",
      "role": "content",
      "text": "The examples on this page were run with RQ 3.0 and redis-py against Redis 7.2. RQ 3.0\nrequires Python 3.10 or later and redis-py 5.0.1 or later. Install it with pip:\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": "enqueue-and-run-jobs",
      "title": "Enqueue and run jobs",
      "role": "content",
      "text": "Put the function that does the work in a module that both the code that enqueues the job\nand the worker can import. This example uses a `tasks.py` module:\n\n[code example]\n\nCreate a `Queue` with a redis-py connection and enqueue the function with its arguments:\n\n[code example]\n\nStart a worker in a separate terminal, in the directory that contains `tasks.py`:\n\n[code example]\n\nAfter the worker runs the job, `job.return_value()` returns `5`. The `--with-scheduler`\noption starts the scheduler that the next two sections need."
    },
    {
      "id": "retry-and-schedule-jobs",
      "title": "Retry and schedule jobs",
      "role": "content",
      "text": "Pass a `Retry` object to retry a job that raises an error, with the wait in seconds before\neach attempt. In a test run, a job that failed twice and succeeded on the third attempt\nfinished with its return value:\n\n[code example]\n\nUse `enqueue_in` to run a job after a delay:\n\n[code example]\n\nA scheduled job runs only while a worker started with `--with-scheduler` is running."
    },
    {
      "id": "what-rq-stores-in-redis",
      "title": "What RQ stores in Redis",
      "role": "content",
      "text": "| Key | Type | Contents |\n|-----|------|----------|\n| `rq:queue:<name>` | list | The IDs of jobs that are waiting to run. |\n| `rq:scheduled:<name>` | sorted set | The jobs scheduled with `enqueue_in`, scored by run time. |\n| `rq:job:<job-id>` | hash | The job: `data`, `status`, `enqueued_at`, `started_at`, `ended_at`, `worker_name`, and so on. |\n| `rq:results:<job-id>` | stream | The job's results. |\n| `rq:finished:<name>` | sorted set | The IDs of finished jobs. |\n| `rq:queues` | set | The names of known queues. |\n| `rq:workers` and `rq:worker:<id>` | set, hash | The registered workers and their state. |\n\nA job's hash expires after its result time to live (TTL). The default is about 500\nseconds, so finished jobs disappear on their own. Set `result_ttl` when you enqueue a job\nto keep them longer."
    },
    {
      "id": "what-happens-to-a-job-when-a-worker-is-killed",
      "title": "What happens to a job when a worker is killed",
      "role": "content",
      "text": "RQ doesn't remove a running job from Redis. It records the job in a *started* registry,\nthe sorted set `rq:wip:<name>`, and the job's status stays `STARTED`. After a worker and\nits work-horse process were stopped with `kill -9` partway through a job with a\n6-second timeout:\n\n- The queue was empty and the started registry held the job, so the job was not lost, but\n  it also did not run again. A new worker started right afterward left it in the started\n  registry for the 24 seconds that the test ran.\n- After the registry entry's expiry passed, RQ's registry cleanup (`StartedJobRegistry.cleanup()`)\n  moved the job to the failed registry with an `AbandonedJobError`.\n\nIn these runs RQ did not re-run an abandoned job. It ends up in the failed registry, and\nyour code decides whether to requeue it. Write jobs so that running one twice is safe."
    },
    {
      "id": "more-information",
      "title": "More information",
      "role": "content",
      "text": "- [RQ documentation](https://python-rq.org/)\n- [RQ on GitHub](https://github.com/rq/rq)"
    }
  ],
  "examples": [
    {
      "id": "requirements-ex0",
      "language": "bash",
      "code": "pip install rq",
      "section_id": "requirements"
    },
    {
      "id": "enqueue-and-run-jobs-ex0",
      "language": "python",
      "code": "# tasks.py\ndef add(x, y):\n    return x + y",
      "section_id": "enqueue-and-run-jobs"
    },
    {
      "id": "enqueue-and-run-jobs-ex1",
      "language": "python",
      "code": "from redis import Redis\nfrom rq import Queue\n\nfrom tasks import add\n\nqueue = Queue(\"default\", connection=Redis(host=\"<your-redis-host>\", port=6379))\n\njob = queue.enqueue(add, 2, 3)\nprint(job.get_status())  # JobStatus.QUEUED",
      "section_id": "enqueue-and-run-jobs"
    },
    {
      "id": "enqueue-and-run-jobs-ex2",
      "language": "bash",
      "code": "rq worker --url redis://<your-redis-host>:6379 --with-scheduler",
      "section_id": "enqueue-and-run-jobs"
    },
    {
      "id": "retry-and-schedule-jobs-ex0",
      "language": "python",
      "code": "from rq import Retry\n\nqueue.enqueue(flaky, retry=Retry(max=3, interval=[1, 1]))",
      "section_id": "retry-and-schedule-jobs"
    },
    {
      "id": "retry-and-schedule-jobs-ex1",
      "language": "python",
      "code": "from datetime import timedelta\n\nqueue.enqueue_in(timedelta(seconds=2), add, 10, 5)",
      "section_id": "retry-and-schedule-jobs"
    }
  ]
}
