{"id":4350,"library":"dramatiq","title":"Dramatiq","description":"Dramatiq is a fast, robust, and performant Python 3 background task processing library. It allows you to defer functions to run in the background, typically using message brokers like Redis or RabbitMQ. Currently at version 2.1.0, it maintains an active development cycle with frequent minor releases and occasional major versions introducing breaking changes.","status":"active","version":"2.1.0","language":"en","source_language":"en","source_url":"https://github.com/Bogdanp/dramatiq","tags":["background tasks","message queue","task queue","async","worker"],"install":[{"cmd":"pip install dramatiq","lang":"bash","label":"Base installation"},{"cmd":"pip install dramatiq[redis]","lang":"bash","label":"With Redis broker"},{"cmd":"pip install dramatiq[rabbitmq]","lang":"bash","label":"With RabbitMQ broker"}],"dependencies":[{"reason":"Redis broker backend. Required for `RedisBroker`.","package":"redis","optional":true},{"reason":"RabbitMQ broker backend. Required for `RabbitmqBroker`.","package":"pika","optional":true},{"reason":"Prometheus metrics integration.","package":"prometheus_client","optional":true}],"imports":[{"symbol":"actor","correct":"from dramatiq import actor"},{"symbol":"set_broker","correct":"from dramatiq import set_broker"},{"symbol":"Broker","correct":"from dramatiq import Broker"},{"symbol":"RedisBroker","correct":"from dramatiq.brokers.redis import RedisBroker"},{"symbol":"RabbitmqBroker","correct":"from dramatiq.brokers.rabbitmq import RabbitmqBroker"},{"symbol":"StubBroker","correct":"from dramatiq.brokers.stub import StubBroker"},{"symbol":"ResultMiddleware","correct":"from dramatiq.middleware import ResultMiddleware"}],"quickstart":{"code":"import dramatiq\nfrom dramatiq.brokers.stub import StubBroker\nimport time\nimport os\n\n# Configure the stub broker for local testing and synchronous processing\n# Note: StubBroker processes tasks directly without a separate worker process.\n# For real applications, use RedisBroker, RabbitmqBroker, etc., with 'pip install dramatiq[broker]'.\nbroker = StubBroker()\ndramatiq.set_broker(broker)\n\n@dramatiq.actor\ndef my_task(name):\n    print(f\"[Task] Starting task for {name}...\")\n    time.sleep(0.01) # Simulate some work\n    print(f\"[Task] Task for {name} completed.\")\n    return f\"Hello, {name}!\"\n\n# Send a message to the broker\nprint(\"Sending message...\")\nmessage = my_task.send(\"World\")\nprint(f\"Sent message with ID: {message.message_id}\")\n\n# With StubBroker, you can explicitly process pending messages\n# In a real application, a 'dramatiq worker' process would handle this.\nbroker.join(drop_messages=True) # Process all pending messages\nprint(\"All stub broker messages processed.\")\n\n# If ResultMiddleware and a backend were configured, you could retrieve results:\n# try:\n#     result = message.get_result(block=True, timeout=1)\n#     print(f\"Task result: {result}\")\n# except Exception as e:\n#     print(f\"Could not get result: {e}\")","lang":"python","description":"This quickstart demonstrates defining and sending a task using Dramatiq with a `StubBroker` for synchronous, in-process execution, ideal for testing. For production, you would configure a `RedisBroker` or `RabbitmqBroker` and run a separate `dramatiq worker` process to consume tasks."},"warnings":[{"fix":"Pass a backend instance (e.g., `RedisBackend()`) when initializing `ResultMiddleware`: `ResultMiddleware(backend=RedisBackend())`.","message":"In v2.0.0, the `ResultMiddleware` constructor now requires a `backend` argument. Previously, it would implicitly try to infer one or default.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"If you relied on the previous behavior where `join()` would attempt to process all tasks regardless of individual failures, explicitly set `fail_fast=False` when calling `StubBroker.join()`.","message":"In v2.0.0, the `StubBroker.join()` `fail_fast` parameter's default value changed from `False` to `True`. This means `join()` will now raise an exception immediately on task failure.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Avoid using Gevent with free-threaded Python versions. Consider alternative concurrency models or using a standard Python runtime if Gevent is critical.","message":"Using Gevent with free-threaded Python (e.g., Python 3.13+) is not recommended by Dramatiq and can lead to unexpected behavior. Dramatiq will issue a warning if this combination is detected.","severity":"gotcha","affected_versions":">=2.1.0"},{"fix":"Always call `dramatiq.set_broker()` explicitly at the entry point of your application or test setup. In tests, use distinct broker instances and reset them as necessary for isolation.","message":"Dramatiq relies on a global broker instance configured via `dramatiq.set_broker()`. In multi-application environments, tests, or concurrent contexts, careful management is needed to ensure the correct broker is active for each operation.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure you install the required extras for your chosen broker and features: `pip install dramatiq[redis]` or `pip install dramatiq[rabbitmq]`.","message":"Specific broker backends (e.g., Redis, RabbitMQ) and other features (e.g., Prometheus metrics) are installed via optional 'extras' (e.g., `pip install dramatiq[redis]`). Forgetting these will result in `ModuleNotFoundError` or similar import errors.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}