{"id":9667,"library":"django-dramatiq","title":"Django Dramatiq","description":"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.","status":"active","version":"0.15.0","language":"en","source_language":"en","source_url":"https://github.com/Bogdanp/django-dramatiq","tags":["django","dramatiq","task-queue","async","background-tasks","celery-alternative"],"install":[{"cmd":"pip install django-dramatiq dramatiq[redis]","lang":"bash","label":"Install with Redis broker"},{"cmd":"pip install django-dramatiq dramatiq[rabbitmq]","lang":"bash","label":"Install with RabbitMQ broker"}],"dependencies":[{"reason":"Required for Django integration.","package":"Django","optional":false},{"reason":"The core task queue library.","package":"Dramatiq","optional":false},{"reason":"Backend for the Redis broker.","package":"redis","optional":true},{"reason":"Backend for the RabbitMQ broker.","package":"pika","optional":true}],"imports":[{"note":"This provides the global Dramatiq broker instance configured by django-dramatiq for decorating tasks.","symbol":"dramatiq","correct":"from dramatiq import dramatiq"}],"quickstart":{"code":"import os\nfrom django.conf import settings\nfrom django.apps import apps\nfrom django.core.management import call_command\n\n# Minimal Django setup for demonstration\nos.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')\n\nif not apps.ready:\n    settings.configure(\n        INSTALLED_APPS=[\n            'django_dramatiq',\n            'myapp'\n        ],\n        DRAMATIQ_BROKER={\n            \"URL\": os.environ.get('DRAMATIQ_BROKER_URL', 'redis://localhost:6379/0'),\n            \"OPTIONS\": {\n                \"decode_responses\": True,\n            },\n        },\n        SECRET_KEY='a-very-secret-key',\n        DEBUG=True,\n        # Add other minimal settings if necessary\n    )\n    apps.populate(settings.INSTALLED_APPS)\n\n\n# --- myapp/tasks.py ---\nfrom dramatiq import dramatiq\nimport time\n\n@dramatiq.actor\ndef my_task(x, y):\n    print(f\"Executing task: {x} + {y}\")\n    time.sleep(1) # Simulate work\n    result = x + y\n    print(f\"Task finished: {x} + {y} = {result}\")\n    return result\n\n\n# --- How to use the task ---\nprint(\"Enqueuing task...\")\nmy_task.send(5, 3)\nprint(\"Task enqueued. Run `python manage.py rundramatiq` in a separate terminal to process it.\")\n\n# In a real Django project, you'd call my_task.send() from a view or signal handler.\n# To run the worker (in a separate shell):\n# python manage.py rundramatiq","lang":"python","description":"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."},"warnings":[{"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//\"`.","message":"The `DRAMATIQ_BROKER` setting in `settings.py` expects a dictionary mapping. Ensure you specify the `URL` and any `OPTIONS` correctly for your chosen broker.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Tasks will not execute if the Dramatiq worker is not running. django-dramatiq provides a specific management command for this.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Configure your `DRAMATIQ_BROKER` in `settings.py` like this:\n```python\nDRAMATIQ_BROKER = {\n    \"URL\": \"redis://localhost:6379/0\",\n    \"OPTIONS\": {\n        \"decode_responses\": True,\n    },\n}\n```","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The underlying Dramatiq library has its own breaking changes. For example, Dramatiq 1.0 introduced significant changes to broker initialization and task decorators.","severity":"breaking","affected_versions":"0.1.0 to 0.7.x (for Dramatiq < 1.0) and 0.8.0+ (for Dramatiq >= 1.0)"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install `dramatiq` with the correct broker extras: `pip install dramatiq[redis]` or `pip install dramatiq[rabbitmq]`.","cause":"The specific broker dependency (e.g., redis, rabbitmq) for Dramatiq was not installed.","error":"ModuleNotFoundError: No module named 'dramatiq.brokers.redis'"},{"fix":"Verify that your broker service is running and accessible from your application's environment. Check the `DRAMATIQ_BROKER` URL in your `settings.py`.","cause":"The Dramatiq broker (e.g., Redis server, RabbitMQ server) is not running or is inaccessible at the configured URL.","error":"ConnectionRefusedError: [Errno 111] Connection refused"},{"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`.","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.","error":"ActorNotFound: No actor named 'my_task' was found."},{"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.","cause":"Dramatiq's default message serializer is JSON, which cannot handle all Python types (e.g., `datetime` objects, custom classes).","error":"TypeError: Object of type <...> is not JSON serializable"}]}