django-absurd

Run background tasks and durable workflows in Django on Postgres. Plugs Absurd, a Postgres-native workflow engine, into Django's Tasks framework, reusing 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

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

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

# Installs the Absurd schema and provisions the queues you declared.
python manage.py migrate

from django.tasks import task


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


# Returns a TaskResult straight away; a worker runs the task.
result = add.enqueue(2, 3)

python manage.py absurd_worker

That's the whole loop. The "default" queue is declared for you, so migrate provisions it without any QUEUES setting of your own.

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))

Documentation

• Documentation — tasks, workflows, cron jobs, workers, cleanup, monitoring, testing, and configuration.
• Runnable examples — three dockerized nanodjango demos (web enqueue+result, beat, and pg_cron), each with one docker compose up.

License

MIT — see LICENSE.