Django
v1.13.0 Apache-2.0z4j-django ยท Upstream project
Django AppConfig integration, zero boilerplate.
Adds z4j as a Django app. Reads settings.Z4J (Z4J_* environment variables win) and CELERY_APP when it needs help locating your Celery app, auto-registers with django_celery_beat for schedule CRUD, and reconciles task state through whichever Celery result backend you configure. System checks warn when your setup drifts.
- Latest
- v1.13.0
- Released
- 2026-10-19
- License
- Apache-2.0
Install
pip install z4j-django Pick an engine
Django + any task engine
Every extra pulls the engine adapter AND its companion scheduler in one shot, so a fresh install never needs a second command.
| Engine | Install command | Bundled scheduler |
|---|---|---|
| Celery recommended | pip install z4j-django[celery] | celery-beat |
| RQ | pip install z4j-django[rq] | rq-scheduler |
| Dramatiq | pip install z4j-django[dramatiq] | APScheduler |
| Huey | pip install z4j-django[huey] | huey-periodic |
| arq | pip install z4j-django[arq] | arq-cron |
| TaskIQ | pip install z4j-django[taskiq] | taskiq-scheduler |
| Every engine (CI / kitchen sink) |
pip install z4j-django[all]
| all of the above |
pip install z4j-django with no extra installs only the framework adapter. Pick an engine extra for the normal case.
Wire it in
# settings.py
INSTALLED_APPS += ["z4j_django"]
Z4J = {
"brain_url": env("Z4J_BRAIN_URL"),
"token": env("Z4J_TOKEN"),
"hmac_secret": env("Z4J_HMAC_SECRET"),
"project_id": env("Z4J_PROJECT_ID"),
"agent_name": env("Z4J_AGENT_NAME", default=None),
}
# That's it. No CELERY_APP, no Z4J_DEV_MODE, no dev_mode kwarg.
# Auto-detect checks the documented candidate layouts. Add CELERY_APP when
# none of those candidates resolves your application. Verify
Confirm the agent reaches the brain
Run the doctor as the same user the service runs under. It checks the on-disk buffer path, DNS, TCP and TLS to the brain, and that the agent runtime starts locally (the Django doctor also lists the engines it detects); it exits 0 on all-green, 1 on any failure. It does not prove the WebSocket upgrade or that the brain accepts the token, so confirm the authenticated connection in the agent log and the dashboard.
python manage.py z4j_doctor
Catches the gunicorn-under-www-data silent startup failure (the agent auto-relocates the buffer to $TMPDIR/z4j-{uid} when $HOME is unwritable), DNS failures, and firewall or certificate problems on the path to the brain. It does not check the token or project id; a rejected token shows up in the agent log as a 4401 close. Add --no-websocket to skip the local runtime probe, --json for scripts. Reference.
What you get
Django-specific features
Engine pairings
Django works with every z4j engine
The framework adapter handles lifecycle and config. Any engine adapter slots in alongside.
Celery
The industry standard, covered end-to-end.
Learn more
RQ
Lightweight Redis queue, fully instrumented.
Learn more
Dramatiq
Middleware-driven Dramatiq observability.
Learn more
Huey
Lightweight Redis/SQLite queue, first-class.
Learn more
arq
Async Redis queue for FastAPI-era Python.
Learn more
taskiq
Broker-agnostic async task framework.
Learn moreOther frameworks