Install & Compatibility
Where this runs
tested against v0.18.0 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 67.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.6s · import 0.000s · 68MB
66MB installed
● package 66MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
register
✓ from mptt import register
✗ from mptt.models import MPTTModel
AlreadyRegistered
✓ from mptt import AlreadyRegistered
✗ from mptt.models import MPTTModel
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`.
# settings.py
INSTALLED_APPS = [
# ...
'mptt',
'myapp', # your app name
# ...
]
# myapp/models.py
from django.db import models
from mptt.models import MPTTModel, TreeForeignKey
class Category(MPTTModel):
name = models.CharField(max_length=50, unique=True)
parent = TreeForeignKey('self', on_delete=models.CASCADE,
null=True, blank=True, related_name='children')
class MPTTMeta:
order_insertion_by = ['name']
def __str__(self):
return self.name
# myapp/admin.py
from django.contrib import admin
from mptt.admin import DraggableMPTTAdmin
from .models import Category
@admin.register(Category)
class CategoryAdmin(DraggableMPTTAdmin):
list_display = ('tree_actions', 'indented_title',)
list_display_links = ('indented_title',)
# Optional: to expand the tree by default
expand_tree_by_default = True
Debug
Known issues
deprecatedThe `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).fixFor 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.
affects: 0.13.0 and newer
gotchaWhen 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.fixAfter any operation that modifies the tree structure, call `instance.refresh_from_db()` on any in-memory objects that might have been affected.
affects: All versions
gotchaThe `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.fixAvoid 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.
affects: All versions
gotchaCalling `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.fixTo 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.
affects: All versions
breakingPrior 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.fixAlways 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.
affects: 0.15.0 and newer
gotchaWhen 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.fixEnsure `MPTTModel` is the first base class in your model's inheritance hierarchy when using multiple inheritance.
affects: All versions
Upgrade
Version history
0.18.0latest on PyPI · released Aug 26, 2025
Audit
Dependencies
DjangorequiredCore dependency for the framework integration.