{"id":3967,"library":"django-mptt","title":"Django MPTT","description":"django-mptt is a reusable Django application that simplifies the implementation of Modified Preorder Tree Traversal (MPTT) for hierarchical data in Django models. It provides tools for managing and working with trees of model instances, including automatic updates for tree structures, custom managers, and admin classes. The current version is 0.18.0, and while it continues to receive compatibility updates for newer Django and Python versions, the project maintainers note that the project is \"currently unmaintained\" in terms of active feature development, suggesting users consider alternatives for new projects.","status":"maintenance","version":"0.18.0","language":"en","source_language":"en","source_url":"https://github.com/django-mptt/django-mptt/","tags":["django","mptt","tree","hierarchical data","database","admin"],"install":[{"cmd":"pip install django-mptt","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for the framework integration.","package":"Django","optional":false}],"imports":[{"symbol":"MPTTModel","correct":"from mptt.models import MPTTModel"},{"symbol":"TreeForeignKey","correct":"from mptt.models import TreeForeignKey"},{"note":"MPTTModelAdmin is the correct class for basic MPTT admin integration, often used as a base for custom admin classes. `AdminMPTTModel` is not a standard import path.","wrong":"from mptt.admin import AdminMPTTModel","symbol":"MPTTModelAdmin","correct":"from mptt.admin import MPTTModelAdmin"},{"symbol":"DraggableMPTTAdmin","correct":"from mptt.admin import DraggableMPTTAdmin"}],"quickstart":{"code":"# settings.py\nINSTALLED_APPS = [\n    # ...\n    'mptt',\n    'myapp', # your app name\n    # ...\n]\n\n# myapp/models.py\nfrom django.db import models\nfrom mptt.models import MPTTModel, TreeForeignKey\n\nclass Category(MPTTModel):\n    name = models.CharField(max_length=50, unique=True)\n    parent = TreeForeignKey('self', on_delete=models.CASCADE,\n                            null=True, blank=True, related_name='children')\n\n    class MPTTMeta:\n        order_insertion_by = ['name']\n\n    def __str__(self):\n        return self.name\n\n# myapp/admin.py\nfrom django.contrib import admin\nfrom mptt.admin import DraggableMPTTAdmin\nfrom .models import Category\n\n@admin.register(Category)\nclass CategoryAdmin(DraggableMPTTAdmin):\n    list_display = ('tree_actions', 'indented_title',)\n    list_display_links = ('indented_title',)\n\n    # Optional: to expand the tree by default\n    expand_tree_by_default = True\n","lang":"python","description":"To get started with django-mptt, add 'mptt' to your `INSTALLED_APPS`. Define your hierarchical model by inheriting from `mptt.models.MPTTModel` and including a `TreeForeignKey` field pointing to 'self' for the parent relationship. Optionally, specify `MPTTMeta.order_insertion_by` for natural ordering. For an interactive admin interface, register your model with `mptt.admin.DraggableMPTTAdmin`."},"warnings":[{"fix":"For new projects, evaluate alternatives. For existing projects, ensure you're on a version compatible with your Django/Python stack and be aware of the lack of new features or bug fixes beyond compatibility.","message":"The `django-mptt` project is officially marked as 'unmaintained'. While it receives compatibility updates, active feature development has ceased. For new projects or if you require ongoing maintenance, consider alternatives like `django-tree-queries` (which leverages PostgreSQL's Recursive CTEs).","severity":"deprecated","affected_versions":"0.13.0 and newer"},{"fix":"After any operation that modifies the tree structure, call `instance.refresh_from_db()` on any in-memory objects that might have been affected.","message":"When performing tree reorganizations (e.g., `insert_at`, `move_to`), existing model instances in your application's memory might become stale and hold outdated MPTT field values. You must manually call `refresh_from_db()` on affected instances to load the updated data from the database.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Avoid storing `tree_id` values for application-level identification. Instead, rely on the root node's primary key or other stable attributes if you need to reference a specific tree.","message":"The `tree_id` field is considered volatile and should not be used to uniquely identify or store references to specific trees in your application logic, as these IDs can change during node movement operations.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To safely delete multiple nodes, iterate and call `.delete()` on each instance, or use `mptt.models.TreeManager().delete()` if you need to delete a specific queryset of subtrees and ensure MPTT fields are recalculated.","message":"Calling `delete()` on a `MPTTModel` instance correctly removes the node and its entire subtree. However, performing bulk deletes directly on a QuerySet (e.g., `MyModel.objects.filter(...).delete()`) will bypass MPTT's hooks and lead to an inconsistent tree structure.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always check the `django-mptt` changelog or PyPI for the specific version's `requires_python` and Django framework classifiers to ensure compatibility with your project's environment.","message":"Prior to version 0.15, django-mptt had broader Python and Django compatibility. Version 0.15 dropped support for Python <3.9 and Django <3.2. Subsequent versions continue to drop older Django/Python support to maintain compatibility with the latest stable releases.","severity":"breaking","affected_versions":"0.15.0 and newer"},{"fix":"Ensure `MPTTModel` is the first base class in your model's inheritance hierarchy when using multiple inheritance.","message":"When using multiple inheritance with `MPTTModel`, it is crucial that `MPTTModel` is the *first* class inherited (e.g., `class MyModel(MPTTModel, OtherMixin):`). Failing to do so can result in `AttributeError: 'NoneType' object has no attribute 'name'` during model validation due to Django's inheritance resolution.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}