Django Dramatiq

0.15.0 · active · verified Fri Apr 17

django-dramatiq is a Django application that seamlessly integrates the Dramatiq task queue library with Django projects. It simplifies broker configuration, task discovery, and provides Django management commands for running workers. The current version is 0.15.0 and it maintains an active release cadence, with several updates per year.

Common errors

```
ModuleNotFoundError: No module named 'dramatiq.brokers.redis'
```
cause The specific broker dependency (e.g., redis, rabbitmq) for Dramatiq was not installed.

fix Install `dramatiq` with the correct broker extras: `pip install dramatiq[redis]` or `pip install dramatiq[rabbitmq]`.
```
ConnectionRefusedError: [Errno 111] Connection refused
```
cause The Dramatiq broker (e.g., Redis server, RabbitMQ server) is not running or is inaccessible at the configured URL.

fix Verify that your broker service is running and accessible from your application's environment. Check the `DRAMATIQ_BROKER` URL in your `settings.py`.
```
ActorNotFound: No actor named 'my_task' was found.
```
cause The Dramatiq worker could not find the task definition. This often happens if the worker isn't correctly discovering task modules or if the task file isn't imported.

fix Ensure your tasks are defined in files that are part of your Django apps and are importable. The `rundramatiq` command automatically discovers tasks in `tasks.py` files within `INSTALLED_APPS`.
```
TypeError: Object of type <...> is not JSON serializable
```
cause Dramatiq's default message serializer is JSON, which cannot handle all Python types (e.g., `datetime` objects, custom classes).

fix Convert non-serializable objects to a serializable format (like strings for `datetime`) before sending to the task, or configure a custom serializer for Dramatiq. Alternatively, pass only basic Python types (strings, numbers, lists, dicts) as task arguments.

Warnings

gotcha The `DRAMATIQ_BROKER` setting in `settings.py` expects a dictionary mapping. Ensure you specify the `URL` and any `OPTIONS` correctly for your chosen broker.
Fix: Always 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//"`.
gotcha Tasks will not execute if the Dramatiq worker is not running. django-dramatiq provides a specific management command for this.
Fix: After 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.
gotcha When 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.
Fix: Configure your `DRAMATIQ_BROKER` in `settings.py` like this: ```python DRAMATIQ_BROKER = { "URL": "redis://localhost:6379/0", "OPTIONS": { "decode_responses": True, }, } ```
breaking The underlying Dramatiq library has its own breaking changes. For example, Dramatiq 1.0 introduced significant changes to broker initialization and task decorators.
Fix: Ensure 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.

Install

pip install django-dramatiq dramatiq[redis] Install with Redis broker
pip install django-dramatiq dramatiq[rabbitmq] Install with RabbitMQ broker

Imports

dramatiq
```
from dramatiq import dramatiq
```
This provides the global Dramatiq broker instance configured by django-dramatiq for decorating tasks.

Quickstart

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

view raw JSON →