django-treebeard

django-treebeard is a library that adds efficient tree data structures to Django models. Rather than forcing one tree-storage strategy on every project, it ships three interchangeable implementations behind the same manager API: Adjacency List (parent foreign key, simple but O(n) for subtree reads), Materialized Path (a sortable path string per node, fast reads with occasional path rewrites on move), and Nested Sets (left/right bounds, very fast subtree reads but costlier writes), plus an experimental PostgreSQL ltree-backed implementation.

Models gain tree behavior through abstract base class inheritance (MP_Node, NS_Node, AL_Node, or LT_Node), so a project’s own fields and Meta options remain untouched. Tree operations — add_child, add_sibling, move, get_children, get_descendants, get_ancestors — live on a Treebeard-aware manager rather than scattered instance methods, and the library ships a MoveNodeForm factory plus a TreeAdmin integration with drag-and-drop reordering in the Django admin.

The project has been actively maintained since 2010, with three major-version lines (v5, v6, v7) receiving concurrent bugfix and security support on staggered end-of-life schedules, and a well-documented v6 migration path for the API’s move from model methods to manager methods.

What You Get

• Four tree backends - Adjacency List, Materialized Path, Nested Sets, and an experimental PostgreSQL ltree implementation, all exposing the same manager methods.
• A manager-centric API - add_root, add_child, add_sibling, move, get_children, get_descendants, get_ancestors, and get_tree live on the model manager, keeping tree logic out of model instances.
• Django admin integration - TreeAdmin and admin_factory provide a lazy-loading, drag-and-drop tree view in the Django admin, rewritten in 7.0 for scalability.
• Form support - movenodeform_factory builds a ModelForm subclass with node-position fields wired up for moving/reparenting through standard Django forms.
• Bulk load/dump helpers - load_bulk/dump_bulk serialize and restore entire trees as nested Python structures, useful for fixtures and data migrations.
• Multi-backend database support - officially supports PostgreSQL, MySQL, MSSQL, and SQLite.

Common Use Cases

• Category or taxonomy trees - an e-commerce or CMS project models nested categories where subtree reads (“all products under Electronics”) must be fast.
• Threaded comments - a forum or discussion app needs parent/child comment nesting with efficient ancestor and descendant queries.
• Org charts and permission hierarchies - an internal tool models reporting structures or scoped permissions that inherit down a tree.
• Admin-managed site navigation or content trees - a project needs editors to reorder and reparent tree nodes directly in the Django admin via drag-and-drop.

Under The Hood

Architecture An abstract Node model in treebeard/models.py defines the shared contract (is_root, is_leaf, is_sibling_of, deprecated instance-method shims) that every backend implements. The actual tree logic lives one level down, in per-backend modules — mp_tree.py (Materialized Path, storing a fixed-width sortable path string and a custom MP_NodeQuerySet.delete() that walks the path prefix tree to avoid orphaning descendants), ns_tree.py (Nested Sets, left/right integer bounds), al_tree.py (Adjacency List, a plain parent FK), and ltree/ (delegates to Postgres’s native extension). Since v6, tree-mutating operations (add_child, move, get_descendants) live on a NodeManager subclass rather than the model instance, and each backend fires Django signals (nodes_deleted, subtree_moved, path_updated) so dependent code can react to structural changes without polling. treebeard/admin.py’s admin_factory and treebeard/forms.py’s movenodeform_factory are thin adapters that generate admin classes and forms bound to whichever backend a project’s model uses.

Tech Stack A pure-Python library built against Django 5.2+ and Python 3.10+, with no runtime dependencies beyond Django itself. It targets PostgreSQL, MySQL, MSSQL, and SQLite uniformly for the AL/MP/NS backends, with an additional Postgres-only ltree backend that relies on that extension’s native operators. Packaging uses setuptools with a dynamic version pulled from treebeard.__version__, and the test extra pins pytest-django and pytest-pythonpath. Linting is enforced via ruff (pyflakes, pycodestyle, isort, pyupgrade rule sets) in CI, and releases publish to PyPI through GitHub Actions’ trusted-publishing flow on tag push.

Code Quality The test suite is unusually large for a library of this scope — a single tests/test_treebeard.py file of roughly 4,700 lines exercises all four backends against a shared fixture tree, alongside dedicated files for benchmarks (test_benchmarks.py), the deprecated pre-6.0 API surface (test_deprecated_api.py), schema migrations (test_migrations.py), and the base-36 path encoding utility (test_numconv.py). The README claims 96%+ branch coverage, and .coveragerc plus CI wiring back that claim up structurally. CI runs ruff linting as a separate job from the test matrix, and deprecation warnings (RemovedInTreebeard8Warning) are tested explicitly rather than left implicit.

API Design The library’s central design bet is presenting four structurally different storage strategies through one identical manager API, so switching backends is a base-class swap rather than a rewrite of calling code — a deliberate ergonomics choice documented in the README’s “Flexible” pitch. The v6 migration (moving tree methods from model instances to the manager) was a considered but disruptive API change, softened by keeping the old call sites working with deprecation warnings and a multi-year staggered EOL schedule across v5/v6/v7. Individual features like the 7.0 max_depth argument on get_tree()/get_descendants() show incremental API refinement driven by real usage rather than a novel underlying algorithm — the tree-storage techniques themselves (materialized path, nested sets, adjacency list) are well-established, textbook approaches.