{
  "schema_version": 2,
  "id": "integrate/dramatiq",
  "title": "Redis with Dramatiq",
  "url": "https://redis.io/docs/latest/integrate/dramatiq/",
  "summary": "Run Python background tasks with Dramatiq and Redis.",
  "tags": [
    "docs",
    "integrate",
    "oss",
    "rs",
    "rc"
  ],
  "last_updated": "2026-11-17T16:15:21Z",
  "children": [],
  "page_type": "content",
  "content_hash": "da7763a2d187b8ed8ea51043daf02c6d57d4206dfb76519a54076997dfee711c",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "[Dramatiq](https://dramatiq.io/) is a Python library for background task processing. You\ndefine *actors*, which are functions that run in worker processes, and send them messages.\nDramatiq supports Redis and RabbitMQ as brokers. 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 Dramatiq 2.2 and redis-py against Redis 7.2.\nDramatiq 2.2 requires Python 3.10 or later. Install it with its Redis dependencies:\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": "configure-the-redis-broker",
      "title": "Configure the Redis broker",
      "role": "configuration",
      "text": "Create a `RedisBroker` and register it with Dramatiq. To store the return values of\nactors, add the `Results` middleware with a Redis backend. This example puts results in a\ndifferent [logical database](https://redis.io/docs/latest/commands/select) from the queues:\n\n[code example]"
    },
    {
      "id": "define-actors-and-send-messages",
      "title": "Define actors and send messages",
      "role": "content",
      "text": "Decorate a function with `@dramatiq.actor`. Set `store_results=True` to keep its return\nvalue, and `max_retries` with a backoff range in milliseconds to retry failures:\n\n[code example]\n\nCall `send()` to queue a message, and `send_with_options()` to set a delay in\nmilliseconds. A message object lets you wait for the stored result:\n\n[code example]\n\nStart a worker in a separate terminal, in the directory that contains `tasks.py`:\n\n[code example]\n\nIn a test run, an actor that raised an error twice logged `Retrying message` for each\nfailure and succeeded on the third attempt."
    },
    {
      "id": "what-dramatiq-stores-in-redis",
      "title": "What Dramatiq stores in Redis",
      "role": "content",
      "text": "| Key | Type | Contents |\n|-----|------|----------|\n| `dramatiq:default` | list | Internal IDs of the messages that are waiting for a worker (`default` is the queue name). |\n| `dramatiq:default.msgs` | hash | The message payloads, keyed by those internal IDs. |\n| `dramatiq:__heartbeats__` | sorted set | The last heartbeat time of each worker process. |\n| `dramatiq:__acks__.<worker-id>.default` | set | The internal IDs of messages that a worker has taken but not yet acknowledged. |\n\nResults go to the database that you gave the results backend, one key for each message,\nwith a time to live (TTL) of about 600 seconds by default."
    },
    {
      "id": "what-happens-to-a-message-when-a-worker-is-killed",
      "title": "What happens to a message when a worker is killed",
      "role": "content",
      "text": "A worker takes a message, runs the actor, and acknowledges the message only afterward, so\na message that a worker was running when it died stays in that worker's `__acks__` set.\nAnother worker puts it back on the queue when two conditions hold. The dead worker's\nheartbeat must be older than the broker's `heartbeat_timeout` (60 seconds by default), and\na worker must run the broker's maintenance, which Dramatiq triggers for a small\nrandom fraction of the broker's Redis commands (`maintenance_chance`, 1,000 in a million by\ndefault).\n\nThe test results show how much those defaults matter. After a worker running a\n100-second job was stopped with `kill -9`:\n\n- With the defaults, a new worker did not run the job again in 204 seconds.\n- With `RedisBroker(..., heartbeat_timeout=5000, maintenance_chance=1000000)`, a new worker\n  started the job 6 seconds after the kill.\n\nPlan for this delay and for double execution: write actors so that running one twice is\nsafe, and set `heartbeat_timeout` to a value that suits how quickly you need recovery."
    },
    {
      "id": "more-information",
      "title": "More information",
      "role": "content",
      "text": "- [Dramatiq documentation](https://dramatiq.io/)\n- [Dramatiq on GitHub](https://github.com/Bogdanp/dramatiq)"
    }
  ],
  "examples": [
    {
      "id": "requirements-ex0",
      "language": "bash",
      "code": "pip install \"dramatiq[redis]\"",
      "section_id": "requirements"
    },
    {
      "id": "configure-the-redis-broker-ex0",
      "language": "python",
      "code": "# tasks.py\nimport dramatiq\nfrom dramatiq.brokers.redis import RedisBroker\nfrom dramatiq.results import Results\nfrom dramatiq.results.backends import RedisBackend\n\nbroker = RedisBroker(url=\"redis://<your-redis-host>:6379/0\")\nbroker.add_middleware(Results(backend=RedisBackend(url=\"redis://<your-redis-host>:6379/1\")))\ndramatiq.set_broker(broker)",
      "section_id": "configure-the-redis-broker"
    },
    {
      "id": "define-actors-and-send-messages-ex0",
      "language": "python",
      "code": "@dramatiq.actor(store_results=True)\ndef add(x, y):\n    return x + y\n\n@dramatiq.actor(max_retries=3, min_backoff=500, max_backoff=2000)\ndef send_email():\n    ...  # raise an exception to trigger a retry",
      "section_id": "define-actors-and-send-messages"
    },
    {
      "id": "define-actors-and-send-messages-ex1",
      "language": "python",
      "code": "message = add.send(2, 3)\nprint(message.get_result(block=True, timeout=10000))  # 5\n\nlate = add.send_with_options(args=(10, 5), delay=2000)\nprint(late.get_result(block=True, timeout=15000))     # 15, after about 3 seconds",
      "section_id": "define-actors-and-send-messages"
    },
    {
      "id": "define-actors-and-send-messages-ex2",
      "language": "bash",
      "code": "dramatiq tasks --processes 1 --threads 2",
      "section_id": "define-actors-and-send-messages"
    }
  ]
}
