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.
pip install dramatiqVerified import paths — ran on the pinned version, not inferred.
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.
Pass a backend instance (e.g., `RedisBackend()`) when initializing `ResultMiddleware`: `ResultMiddleware(backend=RedisBackend())`.
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()`.
Avoid using Gevent with free-threaded Python versions. Consider alternative concurrency models or using a standard Python runtime if Gevent is critical.
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.
Ensure you install the required extras for your chosen broker and features: `pip install dramatiq[redis]` or `pip install dramatiq[rabbitmq]`.
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`).
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)`.
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())`.
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`).