Skip to main content

django-dbos

⚠️ Experimental project. Do not use in production.

A DBOS-backed backend for Django's tasks framework: background tasks that survive a worker crash, cron scheduling, optional Sentry monitoring, an admin UI to inspect and operate on tasks, and a worker capacity report to drive autoscaling.

At a glance

If you know Django's tasks API, you already know django-dbos:

from django.tasks import task


@task
def send_welcome_email(user_id: int) -> None: ...


result = send_welcome_email.enqueue(user_id)  # durable by default
result.status  # READY, RUNNING, SUCCESSFUL, FAILED — standard Django TaskResult

Each enqueued task is recorded in a database before it runs. If the worker executing it crashes, the task is not lost: it runs again once a worker is back.

Why DBOS

Say you send a newsletter to 10,000 users:

from django.tasks import task


@task
def send_newsletter(campaign_id: int) -> None:
    for user_id in User.objects.values_list('id', flat=True):
        send_one_email(user_id, campaign_id)

With most task backends, if the worker is killed at email #6,000 — a deploy, an OOM, a spot instance reclaimed — the retry restarts the task from #1. 6,000 people get the same email twice.

With django-dbos, one option and one call per email turn the loop into a durable, checkpointed workflow:

from django.tasks import task
from django_dbos import dbos_params, get_dbos_context


@dbos_params(durable_operations=True)
@task
def send_newsletter(campaign_id: int) -> None:
    ctx = get_dbos_context()
    for user_id in User.objects.values_list('id', flat=True):
        ctx.run_step(send_one_email, user_id, campaign_id, name=f'email-{user_id}')

Each run_step call is recorded in the system database as it completes. Kill the worker at #6,000, restart it, and the task resumes from there: the 5,999 emails already sent are skipped, and only the one in flight at the moment of the crash may go out again. No external state to reconcile, no idempotency keys to invent yourself.

Cron schedules are just @tasks with a firing time attached — same durability, same retries, same admin page:

from django_dbos import cron


@cron('0 3 * * *')  # every day at 3am
@dbos_params(workflow_timeout=3600, step_retries_allowed=True)
@task
def nightly_report() -> None: ...

Schedules are stored in the system database, so they keep firing across restarts and deploys — and with the sentry extra installed, each firing checks in with Sentry Crons automatically.

What you get

  • Durable tasks — every .enqueue() becomes a DBOS workflow: automatic recovery after a crash, step retries with backoff, deferred execution (run_after), deduplication, priorities and workflow timeouts, all through Django's own Task / TaskResult API.
  • Durable workflows (opt-in) — checkpointed steps, durable sleeps that survive restarts, progress events, messages between workflows and child workflows, from inside a task.
  • Cron scheduling — @cron('0 3 * * *') on top of @task. Every worker fires the schedules, each firing runs once, and no separate scheduler process is needed.
  • Sentry cron monitoring (optional) — scheduled tasks check in with Sentry Crons automatically, no monitor to configure by hand.
  • Admin pages — inspect every workflow (inputs, outputs, errors, step history), and cancel, resume, fork or delete them; manage schedules; see which workers are alive. Superuser-only.
  • Worker capacity report — dbos status (or capacity.collect() from Python) reports backlog, running count and per-worker load per queue, with a scale up/down/OK verdict you can plug into an autoscaler.
  • Structured logging — everything goes through structlog under the django_dbos logger.
  • A pytest plugin — dbos_inline runs enqueued tasks synchronously for fast unit tests; dbos_system launches a real DBOS system database (SQLite or a Postgres testcontainer) when you need real semantics.

Requirements

  • Python 3.12+
  • Django 6.0+
  • A DBOS system database: PostgreSQL (recommended) or SQLite

Installation

uv add django-dbos
# or
pip install django-dbos

Poetry and PDM work too, see Installation. Add the msgspec extra (uv add "django-dbos[msgspec]" or pip install "django-dbos[msgspec]") for fast, safe serialization of task data; see Serialization.

INSTALLED_APPS = [
    ...,
    'django_dbos',
]

TASKS = {
    'default': {
        'BACKEND': 'django_dbos.backends.DBOSBackend',
        'QUEUES': ['default', 'emails'],
        # other django-dbos settings go in 'OPTIONS', see the configuration docs
    },
}
python manage.py migrate       # Django's migrations, then the DBOS system database
python manage.py dbos worker   # start executing tasks

Put your tasks in a tasks.py module of an installed app: that is where the worker looks for them. Your web processes only ever talk to the system database — they enqueue tasks, they never execute them.

New to background tasks? Your first task walks through writing, running and checking one, step by step.

Using an AI coding agent

django-dbos ships an agent skill that teaches AI coding agents (Claude Code, Codex, Cursor, OpenCode, Pi...) how to write tasks, workflows and cron schedules with it. Install it with the skills CLI:

npx skills add lewoudar/django-dbos --skill django-dbos

AI agents has the command for each agent and how to install the skill by hand.

Examples

Two runnable projects in examples/, each a standalone uv project you can uv sync and run on its own:

  • ninja_api — a Django Ninja API that enqueues a task and polls its status until it's done.
  • cron_report — a @cron task that fires on its own once a worker is running, no external scheduler needed.

Documentation

The full documentation lives in docs/ (a hosted version is coming once the repository goes public). Good places to start:

License

MIT

Metadata

Release files for django-dbos 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for django-dbos 0.1.0
File Size Uploaded Provenance Actions
django_dbos-0.1.0.tar.gz 600.9 kB Without provenance Details for django_dbos-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for django-dbos 0.1.0
File Interpreter ABI Platform Actions
django_dbos-0.1.0-py3-none-any.whl Python 3 none any Details for django_dbos-0.1.0-py3-none-any.whl

Total release size: 688.5 kB

Release files / django_dbos-0.1.0.tar.gz

Download URL django_dbos-0.1.0.tar.gz
Size 600.9 kB
Tags Source
SHA-256 checksum
How to use checksums
bd0a2a572fe55a9c7a2de9fe4dee613d914d5e4405ce1e1219ebbd40f60335a6
BLAKE2b-256 checksum
How to use checksums
e69e31c1288b43173bd9c72872ebb1c1deb9ecb15f3213eae6987c95bcefcaf0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / django_dbos-0.1.0-py3-none-any.whl

Download URL django_dbos-0.1.0-py3-none-any.whl
Size 87.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7db1930ceb344131b4c75c6fca62167cd4e83dec1d714ea3419cce890dd9366c
BLAKE2b-256 checksum
How to use checksums
058fe9660c9828c96ccfd8d49a4c9de968b2b8c36c3110dd29a18ec54626b8d0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for django-dbos 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page