---
title: "Django adapter"
description: "Settings-driven BabelQueue for Django — a BABELQUEUE config, get_app()/publish() helpers, and a manage.py babelqueue_worker command."
source: https://babelqueue.com/docs/babelqueue-python/1.x/django/
updated: 2026-06-07T00:00:00.000Z
---

# Django adapter

The Django adapter wires the BabelQueue runtime into a Django project via settings,
with helpers to publish from your code and a management command to run the worker.

## Install

```bash
pip install "babelqueue[django]"
```

The `[django]` extra adds `django>=4.2`. Add the app to `INSTALLED_APPS`:

```python
# settings.py
INSTALLED_APPS = [
    # ...
    "babelqueue.django",
]
```

## Configure

A single `BABELQUEUE` settings dict configures the runtime. `broker_url` selects the
transport; the other recognised keys (`queue`, `on_unknown_urn`, `max_attempts`,
`dead_letter`, `dead_letter_queue`, `dead_letter_suffix`, `transport`) are forwarded
to the runtime:

```python
# settings.py
BABELQUEUE = {
    "broker_url": "redis://localhost:6379/0",
    "queue": "orders",
    "dead_letter": True,
}
```

## Publish

```python
# views.py
from babelqueue.django import publish

def create_order(request):
    publish("urn:babel:orders:created", {"order_id": 1042})
    ...
```

`publish(urn, data, **kwargs) → str` returns the message `meta.id`, using the
process-wide app from `get_app()`.

## Register handlers

Register handlers into the same app the worker uses — the app config's `ready()` is
the natural place:

```python
# apps.py
from django.apps import AppConfig
from babelqueue.django import get_app

class MyAppConfig(AppConfig):
    name = "myapp"

    def ready(self):
        @get_app().handler("urn:babel:orders:created")
        def on_created(data, meta):
            ...
```

## Run the worker

```bash
python manage.py babelqueue_worker --queue orders
```

Options: `--queue` (defaults to the configured queue), `--max-messages` (default:
run until interrupted), `--timeout` (per-poll seconds, default `1.0`).

The messages your Django app produces and consumes are the
[canonical envelope](/docs/spec/1.x/envelope/), interoperable with every BabelQueue SDK.