Skip to main content
Django logo

Django

v1.13.0 Apache-2.0

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

bash
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

python
# 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.

bash
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

Django AppConfig auto-registration
django_celery_beat schedule adapter (read-write)
5-candidate Celery app auto-detect (cookiecutter, ROOT_URLCONF, WSGI/ASGI, BASE_DIR)
Loopback ws:// auto-allowed for local dev (no Z4J_DEV_MODE flag)
Autoreload-parent skip prevents StatReloader 4002 disconnects
Eager z4j-celery import wires worker_init signal in any Django+Celery layout

Engine pairings

Django works with every z4j engine

The framework adapter handles lifecycle and config. Any engine adapter slots in alongside.

Other frameworks

See also

Get started with z4j + Django