Django

Name: z4j for Django
Author: z4j

v1.12.0 Apache-2.0

Django AppConfig integration, zero boilerplate.

Adds z4j as a Django app. Reads DATABASES + CELERY_* from your settings, auto-registers with django_celery_beat for schedule CRUD, plays nice with django-celery-results for state. System checks warn when your setup drifts.

Docs PyPI: z4j-django Source Upstream

Latest: v1.12.0
Released: 2026-10-03
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 probes brain DNS / TCP / TLS / WebSocket upgrade, the on-disk buffer path, and reports auto-detected engines - exits 0 on all-green, 1 on any failure.

bash

python manage.py z4j_doctor

Catches the gunicorn-under-www-data silent startup failure (the agent now auto-relocates the buffer to $TMPDIR/z4j-{uid} when $HOME is unwritable), NAT / firewall / cert mismatches, and wrong-token / wrong-project_id problems with a specific failure reason. Add --no-websocket to skip the WS round-trip, --json for scripts. Reference.

What you get