django-absurd¶

Run background tasks and durable workflows in Django on Postgres. It plugs Absurd, a Postgres-native workflow engine, into Django's built-in Tasks framework and reuses the database connection your project already has.

Install¶

uv add django-absurd

pip install django-absurd

Needs Python 3.12+, Django 6.0+, and PostgreSQL on the psycopg (v3) driver — Absurd reuses Django's connection, so psycopg2 won't work.

Quickstart¶

1. Add the app and point Django's TASKS setting at the backend:

INSTALLED_APPS = [
    # ...
    "django_absurd",
]

TASKS = {
    "default": {
        "BACKEND": "django_absurd.backends.AbsurdBackend",
    },
}

2. Migrate. This installs Absurd's schema and provisions your declared queues:

python manage.py migrate

3. Write a task with Django's @task decorator — anywhere importable:

from django.tasks import task


@task
def add(a: int, b: int) -> int:
    return a + b

4. Enqueue it. Returns a TaskResult; a worker runs it:

result = add.enqueue(2, 3)

5. Run a worker:

python manage.py absurd_worker

That's the whole loop. The task runs on the worker and its result is stored in Postgres — fetch it later with add.get_result(result.id).

Wrap work in steps and a retry resumes instead of redoing:

from django_absurd import get_absurd_context


@task
def pay_for_order(order_id: int, amount: int) -> None:
    # Absurd's workflow context — steps, sleep, events.
    context = get_absurd_context()

    def process_payment():
        return stripe.charges.create(amount=amount)

    # Checkpointed under "process-payment": Absurd stores the result.
    charge = context.step("process-payment", process_payment)
    # If this raises, the retry replays the task but reuses the charge above.
    context.step("send-receipt", lambda: send_receipt(order_id, charge))

Next¶

• Tasks — enqueue with retries and other options, and read results.
• Workflows — checkpointed steps, durable sleep, and events.
• Cron Jobs — run tasks on a recurring cadence.
• Workers — running them, and how runs and retries work.
• Monitoring — logs, the admin, and querying queue state.
• Configuration — every setting, in one place.