blumeops/docs/how-to/authentik/authentik-python-backend-derivation.md

---
title: Build Authentik Python Backend
modified: 2026-02-28
status: active
requires:
  - mirror-authentik-build-deps
  - python314-nixpkgs-compat
tags:
  - how-to
  - authentik
  - nix
---

# Build Authentik Python Backend

Build `authentik-django` — the Python/Django application that forms the core backend of authentik.

## Context

This is the most complex component. The nixpkgs derivation uses `python3.override` with extensive `packageOverrides` to handle authentik's non-standard dependencies:

- **4 in-tree Python packages** built from the monorepo: `ak-guardian`, `django-channels-postgres`, `django-dramatiq-postgres`, `django-postgres-cache`
- **Standard `djangorestframework`** 3.16.1 from PyPI (no longer forked as of 2026.2.0 — the nixpkgs 2025.12.4 reference still uses the fork, but `[tool.uv.sources]` no longer overrides it)
- **Pinned `dramatiq`** at 1.17.1 (upstream uses newer versions that break authentik)
- **Django 5** forced via `django_5` (see [[python314-nixpkgs-compat]])
- **Python 3.14** required (`requires-python = "==3.14.*"`) — needs nixpkgs compat overrides (see [[python314-nixpkgs-compat]])
- **60+ Python dependencies** from nixpkgs

Post-install, the derivation patches hardcoded paths in `settings.py`, `default.yml`, `email/utils.py`, and `files/backends/file.py` to reference Nix store paths.

## What to Do

1. Create a Python package override set that builds the 4 in-tree packages from source
2. Include compat overrides from [[python314-nixpkgs-compat]] (`django_5`, `astor`)
3. Pin `dramatiq` to 1.17.1 (standard `djangorestframework` 3.16.1 from nixpkgs — no longer forked)
4. Build `authentik-django` using `hatchling` as the build backend
5. Apply the 4 `substituteInPlace` patches for Nix store path references
6. Copy lifecycle scripts, `manage.py`, blueprints, and web assets into the output
7. Verify: `python -c "import authentik"` succeeds

## Key Details

- Build backend: `hatchling`
- Entry point: `manage.py` (Django management commands)
- Lifecycle scripts: `lifecycle/` directory (used by Go server and `ak` wrapper)
- Blueprints: `blueprints/` directory (YAML IaC definitions)
- The output must include `web/` assets (email templates reference them)

## Related

- [[build-authentik-from-source]] — Parent goal
- [[authentik-go-server-derivation]] — Depends on this for lifecycle scripts and web assets