Install & Compatibility
Where this runs
tested against v0.15.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 71.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.8s · import 0.000s · 72MB
71MB installed
● package 71MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
dramatiq
✓ from dramatiq import dramatiq
This provides the global Dramatiq broker instance configured by django-dramatiq for decorating tasks.
This quickstart demonstrates how to define and enqueue a Dramatiq task within a Django environment configured by django-dramatiq. It assumes you have Redis running at `localhost:6379`. For a real project, replace the minimal settings configuration with your actual `settings.py` and `manage.py` structure. The task is defined using `dramatiq.actor`, which automatically uses the broker configured via `DRAMATIQ_BROKER` in your Django settings. Remember to run `python manage.py rundramatiq` in a separate process to start the worker that will process these tasks.
import os
from django.conf import settings
from django.apps import apps
from django.core.management import call_command
# Minimal Django setup for demonstration
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')
if not apps.ready:
settings.configure(
INSTALLED_APPS=[
'django_dramatiq',
'myapp'
],
DRAMATIQ_BROKER={
"URL": os.environ.get('DRAMATIQ_BROKER_URL', 'redis://localhost:6379/0'),
"OPTIONS": {
"decode_responses": True,
},
},
SECRET_KEY='a-very-secret-key',
DEBUG=True,
# Add other minimal settings if necessary
)
apps.populate(settings.INSTALLED_APPS)
# --- myapp/tasks.py ---
from dramatiq import dramatiq
import time
@dramatiq.actor
def my_task(x, y):
print(f"Executing task: {x} + {y}")
time.sleep(1) # Simulate work
result = x + y
print(f"Task finished: {x} + {y} = {result}")
return result
# --- How to use the task ---
print("Enqueuing task...")
my_task.send(5, 3)
print("Task enqueued. Run `python manage.py rundramatiq` in a separate terminal to process it.")
# In a real Django project, you'd call my_task.send() from a view or signal handler.
# To run the worker (in a separate shell):
# python manage.py rundramatiq
dramatiq --version
Debug
Known issues
gotchaThe `DRAMATIQ_BROKER` setting in `settings.py` expects a dictionary mapping. Ensure you specify the `URL` and any `OPTIONS` correctly for your chosen broker.fixAlways check your `DRAMATIQ_BROKER` dictionary structure against the documentation. For Redis, typically `"URL": "redis://localhost:6379/0"` and `"OPTIONS": {"decode_responses": True}` are needed. For RabbitMQ, `"URL": "amqp://guest:guest@localhost:5672//"`. affects: All versions
gotchaTasks will not execute if the Dramatiq worker is not running. django-dramatiq provides a specific management command for this.fixAfter enqueuing tasks, ensure you start the worker in a separate terminal using `python manage.py rundramatiq`. Check the worker's output for errors or signs of task processing.
affects: All versions
gotchaWhen using the Redis broker, it's highly recommended to set `decode_responses: True` in your `DRAMATIQ_BROKER` options to ensure string data is returned as Python strings, not bytes.fixConfigure your `DRAMATIQ_BROKER` in `settings.py` like this:
```python
DRAMATIQ_BROKER = {
"URL": "redis://localhost:6379/0",
"OPTIONS": {
"decode_responses": True,
},
}
``` affects: All versions
breakingThe underlying Dramatiq library has its own breaking changes. For example, Dramatiq 1.0 introduced significant changes to broker initialization and task decorators.fixEnsure your `django-dramatiq` version is compatible with your `dramatiq` version. `django-dramatiq` v0.8.0+ requires `dramatiq>=1.0.0`. Always review the release notes for both `django-dramatiq` and `dramatiq` when upgrading major versions of either.
affects: 0.1.0 to 0.7.x (for Dramatiq < 1.0) and 0.8.0+ (for Dramatiq >= 1.0)
Upgrade
Version history
0.15.0latest on PyPI · released Nov 13, 2025
Audit
Dependencies
DjangorequiredRequired for Django integration.
DramatiqrequiredThe core task queue library.
redisoptionalBackend for the Redis broker.
pikaoptionalBackend for the RabbitMQ broker.