{"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":"python","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,"search_vec":"'2.1.0':37 '3':10 'activ':41 'allow':16 'async':61 'background':11,25,55 'break':53 'broker':29 'chang':54 'current':34 'cycl':43 'defer':19 'develop':42 'dramatiq':1,2 'fast':5 'frequent':45 'function':20 'introduc':52 'librari':14 'like':30 'maintain':39 'major':50 'messag':28,57 'minor':46 'occasion':49 'perform':8 'process':13 'python':9 'queue':58,60 'rabbitmq':33 'redi':31 'releas':47 'robust':6 'run':22 'task':12,56,59 'typic':26 'use':27 'version':36,51 'worker':62","created_at":"2026-04-12T08:52:01.033464+00:00","updated_at":"2026-04-16T14:41:52.287213+00:00","problems":[{"fix":"Ensure that the module containing the `@dramatiq.actor` decorated functions is loaded by the worker. When running the `dramatiq` worker CLI, specify the module path (e.g., `dramatiq my_app.tasks` if your actors are in `my_app/tasks.py`).","cause":"The Dramatiq worker received a message for an actor that has not been properly declared or imported into the worker's scope, meaning the worker process cannot find the definition of the requested actor.","error":"dramatiq.errors.ActorNotFound: <actor_name>"},{"fix":"Verify that your message broker service (Redis or RabbitMQ) is running and is accessible from where Dramatiq is being executed. Double-check the broker URL/host/port configuration in your Dramatiq setup code, for example: `broker = RedisBroker(host='your_redis_host', port=6379)`.","cause":"The Dramatiq worker or producer failed to establish a connection with the configured message broker (Redis or RabbitMQ), often due to the broker not running, incorrect host/port, or network issues.","error":"Consumer encountered a connection error: Error <error_code> connecting to <broker_address>. Connection refused."},{"fix":"Convert non-JSON-serializable arguments to a serializable format (e.g., `datetime` objects to ISO 8601 strings or timestamps) before sending the message. Alternatively, implement a custom JSON encoder and decoder and configure Dramatiq to use it via `dramatiq.set_encoder(MyCustomEncoder())`.","cause":"Dramatiq uses JSON for message serialization by default, and this error occurs when an actor is sent arguments that are not natively JSON-serializable (e.g., `datetime.datetime` objects, custom class instances).","error":"TypeError: Object of type <type> is not JSON serializable"},{"fix":"Ensure that the directory containing your module is on Python's path (e.g., by running from the correct working directory or configuring `PYTHONPATH`). When using the `dramatiq` CLI, provide the module name without the `.py` extension (e.g., `dramatiq my_app.tasks` instead of `dramatiq my_app/tasks.py`).","cause":"When running the `dramatiq` CLI worker, the specified module containing actors cannot be found in Python's `sys.path`, or the command was used with a `.py` file extension which is incorrect for module paths.","error":"ModuleNotFoundError: No module named '<module_name>'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.2.0","cli_name":"dramatiq","cli_version":"2.1.0","type":"library","homepage":"https://dramatiq.io","github":"https://github.com/Bogdanp/dramatiq","docs":"https://dramatiq.io","changelog":"https://dramatiq.io/changelog.html","pypi":"https://pypi.org/project/dramatiq/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["workflow","database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}