{"id":2006,"library":"django-treebeard","title":"Django Treebeard","description":"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.","status":"active","version":"5.0.5","language":"en","source_language":"en","source_url":"https://github.com/django-treebeard/django-treebeard","tags":["django","tree","orm","mptt","materialized path","adjacency list","nested sets","hierarchical data"],"install":[{"cmd":"pip install django-treebeard","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core framework integration; version 5.x requires Django 4.2+.","package":"Django","optional":false}],"imports":[{"symbol":"MP_Node","correct":"from treebeard.mp_tree import MP_Node"},{"symbol":"AL_Node","correct":"from treebeard.al_tree import AL_Node"},{"symbol":"NS_Node","correct":"from treebeard.ns_tree import NS_Node"}],"quickstart":{"code":"from django.db import models\nfrom treebeard.mp_tree import MP_Node\n\n# Define a simple tree model inheriting from MP_Node (Materialized Path)\n# This is generally the recommended tree type for most use cases.\nclass Category(MP_Node):\n    name = models.CharField(max_length=255)\n\n    # Crucial for deterministic ordering of siblings\n    node_order_by = ['name']\n\n    class Meta:\n        verbose_name_plural = 'categories'\n\n    def __str__(self):\n        return self.name\n\n# Example usage (e.g., in a Django shell or view):\n# Create root nodes\n# root1 = Category.add_root(name='Electronics')\n# root2 = Category.add_root(name='Books')\n\n# Add children to root1\n# phone = root1.add_child(name='Phones')\n# laptop = root1.add_child(name='Laptops')\n\n# Add a grandchild to phone\n# iphone = phone.add_child(name='iPhones')\n\n# Retrieve and traverse\n# for node in Category.get_tree():\n#     print(f\"{'--' * node.depth} {node.name}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.10+ and Django to 4.2+ before upgrading `django-treebeard` to version 5.x.","message":"Version 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+.","severity":"breaking","affected_versions":"<5.0.0 to 5.x"},{"fix":"Always include `node_order_by = ['your_field_name']` in your tree model definition, specifying the fields by which sibling nodes should be ordered.","message":"All 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.","severity":"gotcha","affected_versions":"All"},{"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`.","message":"The `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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"Adding 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}