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 ownTask/TaskResultAPI. - 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(orcapacity.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_dboslogger. - A pytest plugin —
dbos_inlineruns enqueued tasks synchronously for fast unit tests;dbos_systemlaunches 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@crontask 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:
- Your first task — a hands-on walkthrough.
- Tasks and Workflows — options, retries, durable primitives.
- Cron scheduling — schedules and Sentry monitors.
- Deployment — what to settle before production.
- Troubleshooting — the errors you are most likely to meet.
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.