Skip to content

Installation Modes

Choose The Smallest Install That Matches The Job

Use codex-django in one of three practical modes:

  1. Runtime library mode for projects that only need reusable Django modules.
  2. Scaffold mode for developers generating or extending a Codex-shaped project with codex-django-cli.
  3. Full contributor mode for people changing the library itself.

Runtime Library Mode

Install only the package and the extras your Django project actually uses:

pip install codex-django
pip install "codex-django[cli]"
pip install "codex-django[admin,observability]"
pip install "codex-django[dev]"

This mode is for teams consuming runtime modules such as core, system, booking, messaging, and cabinet. The base install intentionally avoids debug toolbar, admin-theme, and metrics packages; install admin for django-unfold, observability for django-prometheus, and dev for contributor/debug tooling.

Scaffold Mode

Use the companion CLI package when you want to generate a new project or add feature scaffolds to an existing one:

pip install "codex-django[cli]"
# or: pip install codex-django-cli
codex-django init myproject --with-booking --with-messaging
codex-django menu

The CLI is no longer part of the runtime distribution. The CLI is a standalone generator; its generated projects depend on codex-django. The runtime package's optional [cli] extra installs the generator alongside the runtime.

Contributor Mode

When you are changing codex-django itself, sync the full development environment:

uv sync --extra maintainer
uv run pytest
uv run mypy src/
uv run pre-commit run --all-files
uv run python tools/dev/check.py --ci
uv build --no-sources

Production Guidance

  • Put generated project code into your application repository.
  • Treat scaffolding as a build-time or developer-time activity.
  • Keep production images focused on the dependencies your runtime application actually needs.
  • Avoid making the deployed app container depend on interactive CLI flows unless that is an explicit operational choice.

Where To Go Next