Compatibility matrix

This is the authoritative compatibility table for the z4j ecosystem. Each row shows the upstream framework / engine / scheduler version range the matching z4j adapter is tested and shipped against.

Reading the matrix

Min is the lowest upstream version z4j's adapter still imports cleanly and exposes the full action surface against. Older releases may work for read-only paths; we do not test them.
Cap is an explicit upper bound, set only where the upstream library has shipped (or is about to ship) a breaking-major that rewrites the API surface z4j depends on. "none" means the adapter declares no upper cap; it is not a guarantee about untested future releases.
Python is the runtime floor for the package. All shipped z4j packages require Python 3.11+.
Pip pin is a copy-pasteable line you can drop into a requirements.txt or pip install invocation alongside the z4j package.

Brain and companion processes

Component	Python	Notes
`z4j` (brain)	3.11+	PostgreSQL 17+ for production; bundled SQLite for single-node.
`z4j-bare` (agent harness)	3.11+	Pure-Python runtime; no framework or engine pinned.
`z4j-scheduler` (companion process)	3.11+	Fans out to whichever engines you install on the same host.
`z4j-core` (shared protocols)	3.11+	Transitive dependency shared by every adapter.

Framework adapters

z4j package	Upstream	Min	Cap	Python	Pip pin
`z4j-django`	Django	4.2	none	3.11+	`pip install "z4j-django"`
`z4j-flask`	Flask	2.3.3	none	3.11+	`pip install "z4j-flask" "flask>=2.3.3"`
`z4j-fastapi`	FastAPI	0.109.1	none	3.11+	`pip install "z4j-fastapi" "fastapi>=0.109.1"`

The adapter ranges express API compatibility, not a requirement to upgrade every host application to our development versions. Django 4.2 and 5.2 installations can keep their framework line; choose a Python version supported by that Django release. Django 6.1.1, FastAPI 0.141.1 and Flask 3.1.3 are also covered by current-framework CI. An environment that installs django-celery-beat 2.9 must respect its own Django <6.1 constraint.

Use supported upstream lines and current security patches for production. Legacy API compatibility does not certify the host application's security. Z4J's deployment locks and security audits remain separate from these public adapter ranges.

The shared core accepts Pydantic 2.9.2+ on Python 3.11 through 3.13 and Pydantic 2.12+ on Python 3.14+, plus typing-extensions 4.12.2+. CI tests older, LTS and current framework profiles, including core validation and real adapter discovery. The Brain and scheduler are separate services with their own audited dependency requirements.

Engine adapters

z4j package	Upstream	Min	Cap	Python	Pip pin
`z4j-celery`	Celery	5.2.2	none	3.11+	`pip install "z4j-celery" "celery>=5.2.2"`
`z4j-rq`	RQ	1.10.1	`<3`	3.11+	`pip install "z4j-rq" "rq>=1.10.1,<3"`
`z4j-dramatiq`	Dramatiq	1.14	`<3`	3.11+	`pip install "z4j-dramatiq" "dramatiq>=1.14,<3"`
`z4j-huey`	Huey	2.4	`<3`	3.11+	`pip install "z4j-huey" "huey>=2.4,<3"`
`z4j-arq`	arq	0.26	`<1`	3.11+	`pip install "z4j-arq" "arq>=0.26,<1"`
`z4j-taskiq`	TaskIQ	0.11	`<1`	3.11+	`pip install "z4j-taskiq" "taskiq>=0.11,<1"`

Scheduler adapters

z4j package	Upstream	Min	Cap	Python	Pip pin
`z4j-celerybeat`	Celery + `django-celery-beat`	5.3 + 2.5	none	3.11+	`pip install "z4j-celerybeat" "celery>=5.3" "django-celery-beat>=2.5"`
`z4j-rqscheduler`	`rq-scheduler`	0.11	none	3.11+	`pip install "z4j-rqscheduler" "rq-scheduler>=0.11"`
`z4j-apscheduler`	APScheduler	3.10.2	`<4`	3.11+	`pip install "z4j-apscheduler" "apscheduler>=3.10.2,<4"`
`z4j-hueyperiodic`	Huey	2.4	`<4`	3.11+	`pip install "z4j-hueyperiodic" "huey>=2.4,<4"`
`z4j-arqcron`	arq	0.26	`<1`	3.11+	`pip install "z4j-arqcron" "arq>=0.26,<1"`
`z4j-taskiqscheduler`	TaskIQ	0.11	`<1`	3.11+	`pip install "z4j-taskiqscheduler" "taskiq>=0.11,<1"`

Cap rationale

The upper caps exist only where upstream has shipped or imminently ships a breaking-major:

RQ <3 -- RQ 3.0 is a Worker / Queue API rewrite. The cap lifts once z4j-rq ships a 3.x-compatible code path.
Dramatiq <3 -- conservative breaking-major guard; the active tested range is the 2.x line.
Huey <3 for the engine adapter, <4 for the periodic-task adapter -- Huey 3 adds timeout/rate-limit lifecycle signals and expands its pickled queue message. A 3.x worker can consume queued 2.x work, but a 2.6 rollback cannot deserialize work enqueued by 3.x. The engine cap stays until signal terminal/retry behavior and a safe rollback protocol are both executable gates. The read-only periodic adapter is registry-based and tolerates 2.x and 3.x.
APScheduler <4 -- APScheduler 4.x is a full rewrite (new scheduler / data-store API). Stay on 3.x until a 4.x branch ships.
arq <1, TaskIQ <1 -- both libraries are still pre-1.0; the caps prevent silent breakage when their 1.0 lines land.

Django 6 requires Python 3.12+, which its own package metadata enforces. No adapter cap is applied to Django, Flask, FastAPI, Celery, rq-scheduler, or django-celery-beat. Their deprecation policies have historically been gradual enough that adapter breakage surfaces as a feature gap rather than an import error.

Engine pairing extras

Framework adapters expose [engine] extras that pull the engine adapter AND its companion scheduler in one shot:

pip install "z4j-django[celery]"    # z4j-celery + z4j-celerybeat
pip install "z4j-django[rq]"        # z4j-rq + z4j-rqscheduler
pip install "z4j-django[dramatiq]"  # z4j-dramatiq + z4j-apscheduler
pip install "z4j-django[huey]"      # z4j-huey + z4j-hueyperiodic
pip install "z4j-django[arq]"       # z4j-arq + z4j-arqcron
pip install "z4j-django[taskiq]"    # z4j-taskiq + z4j-taskiqscheduler
pip install "z4j-django[all]"       # every engine (CI / kitchen sink)

The same extras exist on z4j-flask and z4j-fastapi. z4j-bare has no engine extras, so install its adapters directly, for example pip install z4j-bare z4j-celery z4j-celerybeat. Pip resolves the matching adapter version automatically; you only need to pin the upstream library when your application already pins it elsewhere.

Brain and agent version skew

A fleet does not upgrade all at once, so a supported amount of skew is part of the contract rather than something you get away with.

The brain leads and agents follow. The brain may run up to one minor version ahead of an agent within the same major line. A brain and an agent on the same minor is the steady state; a brain one minor ahead is the supported rolling-upgrade state.

Pairing	Supported
Same minor	Yes
Brain one minor ahead of agent	Yes, this is the rolling-upgrade window
Brain two or more minors ahead	No, upgrade the agent
Agent ahead of brain	No, upgrade the brain first
Different majors	No

The practical consequence is the upgrade order: upgrade the brain first, watch it, then roll the agents on your own schedule. You do not need a window in which everything moves together.

The agent reports its version on every connection, so an unsupported pairing is something the brain can see rather than infer from behaviour. Adapter package floors are coordinated across a release for the same reason, so a current adapter cannot be installed beside a dispatcher too old to honour its contract.

If you skip a minor on the brain, stop at the intermediate release long enough to roll the agents before going further. The schema will span the jump, but the agents will not.

Wire protocol

All agents and brains within the same major line talk over the same wire protocol. Cross-version mismatches inside a major surface as a dashboard banner; cross-major mismatches close the WebSocket with 4426 (Upgrade Required). See versioning and the changelog for the per-release numbers.