Registry / database / django-treebeard

django-treebeard

JSON →
library7.0.1pypypi✓ verified 29d ago

django-treebeard is a Django library providing efficient implementations for tree structures using Materialized Path (MPTT), Adjacency List, and Nested Sets algorithms. It offers a robust way to manage hierarchical data directly within Django models. The current stable version is 5.0.5, with releases typically aligning with Django's major versions to maintain compatibility and introduce new features.

pip install django-treebeard
INSTALL
IMPORT
SIG · DJANGO-TREEBEARD
D
django-treebeard
databasepythonv7.0.1
Install
3.6s avg
Import
—
Disk
66MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v7.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 66.9MB
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 3.6s · import 0.000s · 67MB
66MB installed
● package 66MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

MP_Node
✓ from treebeard.mp_tree import MP_Node
✗ from treebeard.mp_tree import MP_Node

Defines a basic `Category` model using `MP_Node` (Materialized Path) and demonstrates how to initialize the tree and add nodes. Remember to run `makemigrations` and `migrate` after defining your model. `node_order_by` is critical for consistent tree ordering.

from django.db import models from treebeard.mp_tree import MP_Node # Define a simple tree model inheriting from MP_Node (Materialized Path) # This is generally the recommended tree type for most use cases. class Category(MP_Node): name = models.CharField(max_length=255) # Crucial for deterministic ordering of siblings node_order_by = ['name'] class Meta: verbose_name_plural = 'categories' def __str__(self): return self.name # Example usage (e.g., in a Django shell or view): # Create root nodes # root1 = Category.add_root(name='Electronics') # root2 = Category.add_root(name='Books') # Add children to root1 # phone = root1.add_child(name='Phones') # laptop = root1.add_child(name='Laptops') # Add a grandchild to phone # iphone = phone.add_child(name='iPhones') # Retrieve and traverse # for node in Category.get_tree(): # print(f"{'--' * node.depth} {node.name}")
Debug
Known issues
breakingVersion 5.x of `django-treebeard` dropped support for older Python and Django versions. Specifically, `django-treebeard` 5.x requires Python 3.10+ and Django 4.2+.
fix
Upgrade your Python environment to 3.10+ and Django to 4.2+ before upgrading `django-treebeard` to version 5.x.
affects: <5.0.0 to 5.x
gotchaAll concrete (non-abstract) tree models must define `node_order_by` as a list of field names. Failing to do so will result in a `TreebeardMissingNodeOrderBy` exception or non-deterministic sibling ordering.
fix
Always include `node_order_by = ['your_field_name']` in your tree model definition, specifying the fields by which sibling nodes should be ordered.
affects: All
gotchaThe `AL_Node` (Adjacency List) implementation is significantly less efficient for tree traversal operations (like fetching descendants or ancestors) compared to `MP_Node` or `NS_Node`, especially with deep or large trees.
fix
For most use cases, especially those requiring frequent traversal or large trees, prefer `MP_Node` (Materialized Path) or `NS_Node` (Nested Sets) over `AL_Node`.
affects: All
gotchaAdding a Treebeard model to an existing table that already contains data requires careful data migration to correctly populate the tree fields (path, depth, numchild, etc.). Simply running `migrate` will likely result in errors or an invalid tree.
fix
After creating the model, run `makemigrations`, then manually run the `fix_tree` management command (`python manage.py fix_tree your_app_name.YourTreeModel`) to initialize the tree fields for existing data.
affects: All
Upgrade
Version history
7.0.1latest on PyPI · released Aug 19, 2026
Audit
Dependencies
DjangorequiredCore framework integration; version 5.x requires Django 4.2+.
Agent activity
17 hits · last 30 days
node
14
OpenAI (training)
1
Resources
django-treebeard — pip install django-treebeard · libregistry