blumeops/docs/how-to/authentik/python314-nixpkgs-compat.md

---
title: Python 3.14 Nixpkgs Compatibility Overrides
modified: 2026-02-28
status: active
requires:
  - mirror-authentik-build-deps
tags:
  - how-to
  - authentik
  - nix
---

# Python 3.14 Nixpkgs Compatibility Overrides

Document and implement the `packageOverrides` needed to build authentik's Python dependency tree under `python314` on nixos-25.11.

## Problem

Authentik 2026.2.0 requires Python 3.14 (`requires-python = "==3.14.*"`). The nixos-25.11 channel's `python314` package set has four issues:

1. **`astor` 0.8.1** — test suite uses `ast.Num`, `ast.Str`, and `ast.NameConstant`, which were removed in Python 3.14. Build fails during `pytestCheckPhase`.
2. **`django` defaults to 4.2.x** — Django 4.2 does not support Python 3.14. The `python314.pkgs.django` attribute points to `django_4` (4.2.28), not `django_5`.
3. **`dacite` 1.9.2** — test asserts on `typing.Union[int, str]` string representation, but Python 3.14 renders it as `int | str`. Cosmetic test failure; functionality is fine.
4. **`exceptiongroup` 1.3.0** — tests expect `RecursionError` on deep nesting, but Python 3.14 increased the recursion limit. The module is a no-op shim on Python 3.11+ anyway.

The astor and django failures cascade through the dependency graph, breaking `trio` → `anyio` → `httpcore`/`azure-core`/etc. and ultimately `authentik-django`.

## Research Findings

### astor

Current nixpkgs (unstable/newer 25.11 snapshots) already fixes this:

- Uses an **unstable git snapshot** `df09001112f079db54e7c5358fa143e1e63e74c4` (2024-03-30), not the 0.8.1 release
- Carries `python314-compat.patch` from upstream PR [#233](https://github.com/berkerpeksag/astor/pull/233)
- The patch replaces removed `ast.Num`/`ast.Str`/`ast.NameConstant` with `ast.Constant` and guards affected tests with version checks
- Hash: `sha256-VF+harl/q2yRU2yqN1Txud3YBNSeedQNw2SZNYQFsno=`

Ringtail's nixos-25.11 registry pin predates this fix. Rather than updating the system-wide nixpkgs (which has broader implications), we carry the override in our derivation.

### django

The nixpkgs authentik `package.nix` (2025.12.4) includes `django = final.django_5;` in its `packageOverrides`. This is still needed for 2026.2.0 — `python314` does not default to Django 5.x.

### Dependency chain (astor failure cascade)

```
astor (test failure)
├── trio (nativeCheckInputs)
│   └── anyio
│       ├── httpcore → httpx → msgraph-sdk, azure-core, ...
│       └── azure-core → azure-identity, azure-storage-blob
├── djangoql (runtime dep of authentik)
└── django 4.2.28 (also broken, separate issue)
    └── authentik-django (1 dependency failed)
```

## What to Do

Add these overrides to `authentik-django.nix`'s `packageOverrides` block:

1. **`django = final.django_5;`** — same as nixpkgs authentik does
2. **`astor`** — override to use the patched git snapshot with the python314-compat.patch, matching what current nixpkgs does (NOT just disabling tests)
3. **`dacite`** — disable `test_from_dict_with_union_and_wrong_data` (cosmetic string repr change, not a functional issue)
4. **`exceptiongroup`** — disable `test_deep_split` and `test_deep_subgroup` (recursion limit change, module is a no-op shim on 3.11+)

The override for astor should use `fetchFromGitHub` with owner `berkerpeksag`, repo `astor`, rev `df09001112f079db54e7c5358fa143e1e63e74c4`, and carry the patch from nixpkgs PR #233. This is a proper fix, not a test skip.

## Related

- [[authentik-python-backend-derivation]] — Parent card (depends on this)
- [[build-authentik-from-source]] — Root goal