NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI
PyPI, #4002 most downloaded on PyPI
Utilities for implementing Modified Preorder Tree Traversal with your Django Models and working with trees of Model instances.
Latest stable
0.21.1
Last release 19 days ago
03 Nov 2026
Release timing varies
gaps range from 1 weeks to 1.2 years
Some releases are documented
notes for 22 of 49 stable releases
Nothing withdrawn
no release was ever pulled
19 years old
50 releases · first in 2008
Drag across the ruler to compare, or tap a release to open it.
TreeRelatedFieldListFilter now reuses Django's RelatedFieldListFilter.queryset() instead of an outdated copy of it, which fixes the filter on Django 5
TreeRelatedFieldListFilter now reuses Django's RelatedFieldListFilter.queryset() instead of an outdated copy of it, which fixes the filter on Django 5 and newer (#854).
Fixed tree methods of proxy models with a filtering custom manager (e.g. get_queryset().filter(level=2)) only seeing the filtered rows: e.g. get_root(
Fixed tree methods of proxy models with a filtering custom manager (e.g. get_queryset().filter(level=2)) only seeing the filtered rows: e.g. get_root() raised DoesNotExist, and inserting nodes through such a manager corrupted the tree. Tree operations now use an unfiltered tree manager bound to the proxy model, so they still return proxy instances (fixes #853, regression in 0.19).
TreeManager.db_manager() now passes the database on to the manager that proxy and multi-table inheritance models delegate tree operations to.
Tree writes (inserting, moving and deleting nodes, rebuild(), partial_rebuild(), build_tree_nodes()) now always see every row, even if the model's tree manager is a TreeManager subclass which filters get_queryset(). Previously, hidden nodes could lead to crashes or a corrupted tree, e.g. duplicate tree ids or child nodes left behind in the wrong tree. Positions for order_insertion_by now also take hidden siblings into account. Read methods such as get_children() still apply the filter.
Your coding agent can read these notes before it upgrades. Set up the MCP server →
DraggableMPTTAdmin now uses Script(src, attrs) instead of the deprecated JS(src, {...}) form of django-js-asset, and requires django-js-asset>=4.0.
DraggableMPTTAdmin now uses Script(src, **attrs) instead of the deprecated JS(src, {...}) form of django-js-asset, and requires django-js-asset>=4.0.
Fixed move_to() / TreeManager.move_node() corrupting the tree when the node or the target instance was loaded before other nodes were moved; their tre
Fixed move_to() / TreeManager.move_node() corrupting the tree when the node or the target instance was loaded before other nodes were moved; their tree fields (and the node's parent) are now reloaded from the database before the move (#257, #568).
Fixed delay_mptt_updates() leaving a gap in the old tree when a node was moved out of it; the old tree is now rebuilt as well when the block exits (fixes #483).
Documented why transaction.atomic() alone does not prevent concurrent writes from corrupting the tree and how to serialize tree writes.
Added support for Python 3.14, Django 6.0 and Django 6.1.
Added support for Python 3.14, Django 6.0 and Django 6.1.
Fixed is_root_node() incorrectly returning True for unsaved instances that have a parent assigned but not yet saved (fixes #617).
Fixed _is_saved() always returning True for models with a UUID primary key or any other auto-generated non-None PK by using _state.adding instead of checking pk is None (fixes #514).
Removed the unnecessary get_absolute_url() call per row in DraggableMPTTAdmin.tree_actions(); the resulting data-url attribute was not used by the drag-and-drop JavaScript and caused N+1 queries when get_absolute_url() traversed the tree (fixes #782).
Fixed delete_selected_tree admin action crashing with CantDisableUpdates when used with a proxy model; it now correctly calls delay_mptt_updates() on the underlying concrete model (fixes #615).
Fixed save(using=...) and delete(using=...) ignoring the specified database for MPTT tree management queries; they now route raw SQL and queryset operations to the correct database instead of always falling back to default (fixes #685).
Fixed duplicate tree_id values when saving a root node after changing its order_insertion_by field while other root nodes have already been reshuffled since the instance was loaded. The MPTT tree fields are now refreshed from the database before the repositioning move so that _make_sibling_of_root_node operates on the correct rows (fixes #687).
Fixed TreeRelatedFieldListFilter crashing with a KeyError when the foreign key uses to_field pointing to a non-PK field; both field_choices() and queryset() now look up related objects by the referenced field rather than always assuming pk (fixes #693).
Fixed get_queryset_descendants() and get_queryset_ancestors() incorrectly including contiguous input siblings in their results when the bounding-box range spanned intermediate siblings; a level constraint is now added to each range filter (fixes #517).
Fixed get_family() bypassing the _base_manager delegation used by MTI-based models such as django-polymorphic-tree (fixes #709).
Fixed get_ancestors(), get_descendants(), get_children() and related methods returning instances of the concrete model instead of the proxy model when called on a proxy model instance. The tree manager for proxy models no longer delegates queryset operations to the concrete model's manager, since proxy models share the same database table (fixes #802).
Fixed get_children() issuing a slow pk__in query after get_cached_trees(); it now filters by parent and reuses the cached children as the queryset's result cache (fixes #587).
Fixed validation errors from list_editable forms not being shown in the MPTT admin change list; mptt_results() now yields Django's ResultList so the template can access the row's form (fixes #726).
Fixed the model_bakery guard crashing with an IndexError on Windows because it split the caller's path on / (#852).
Nothing published for this version
Fixed the way indexes are defined for Django 5 and better.
Fixed the way indexes are defined for Django 5 and better.
Added support for Python 3.13 and Django 5.1 and 5.2.
Added support for Python 3.13 and Django 5.1 and 5.2.
Dropped Django < 4.2.
Fixed get_cached_trees if there are multiple trees in the queryset.
Fixed get_cached_trees if there are multiple trees in the queryset.
Added support for Python 3.12, Django 5.0.
Added codespell and ruff checks to the CI.
Fixed rebuilding using custom managers not named objects.
Since I unfortunately still depend on django-mptt in prehistoric projects I took it upon me to make it runnable again. This doesn't mean I want to mai
Since I unfortunately still depend on django-mptt in prehistoric projects I took it upon me to make it runnable again. This doesn't mean I want to maintain the package.
Added Django 4.2.
Dropped Python < 3.9, Django < 3.2.
Started using ruff and more rules.
Dropped the index_together check on Django 5 and better. Django 5 only supports Meta.indexes.
Optimized tree rebuilding.
Added support for the Django admin theme switcher.
Switched to hatchling.
Merged the docs/upgrade.rst file into the main CHANGELOG.rst.
Merged the docs/upgrade.rst file into the main CHANGELOG.rst.
Fixed the Sphinx autodoc configuration to also work locally. Ensured that readthedocs is able to build the docs again.
Fixed a bug where DraggableMPTTAdmin assumed that the user model's primary key is called id.
Ensured that we do not install the tests.myapp package.
Added dark mode support to the draggable model admin.
Started using pre-commit, for the fun of it.
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
MARKED THE PROJECT AS UNMAINTAINED, WHICH IT STILL IS
MARKED THE PROJECT AS UNMAINTAINED, WHICH IT STILL IS
Reformatted everything using black, isort etc.
Switched from Travis CI to GitHub actions.
Switched to a declarative setup.
Verified compatibility with Django up to 3.2 and Python up to 3.9. Dropped compatibility guarantees (ha!) with anything older than Django 2.2 and Python 3.6.
Renamed the main development branch to main.
Fixed a problem where our _get_user_field_names mistakenly returned abstract fields.
Added a workaround for the default_app_config warning.
Changed saving to always call get_ordered_insertion_target when using ordered insertion.
Made it possible to override the starting level when using the tree node choice field.
Fix an issue where the rebuild() method would not work correctly if you were using multiple databases.
Add support for Django 3.1
Drop support for Django 1.11.
Drop support for Python 3.5.
Fix an issue where the rebuild() method would not work correctly if you were using multiple databases.
Update spanish translations.
Add an admin log message when moving nodes when using the DraggableMPTTAdmin admin method.
Add support for Django 3.0.
Add support for Python 3.8.
Add an admin log message when moving nodes when using the DraggableMPTTAdmin admin method.
Fix _is_saved returning False when pk == 0.
Add an all_descendants argument to drilldown_tree_for_node.
Add traditional Chinese localization.
properly log error user messages at the error level in the admin.
Drop support for Pythons 3.4 and Python 2.
Drop support for Pythons 3.4 and Python 2.
Add support for Python 3.7.
Add support for Django 2.1 and 2.2.
Fix get_cached_trees to cleanly handle cases where nodes' parents were not included in the original queryset.
Add a build_tree_nodes method to the TreeManager Model manager to allow for efficient bulk inserting of a tree (as represented by a bulk dictionary).
Support for Django 2.1 has been added, support for Django<1.11 is removed. Support for deprecated South has been removed.
Support for Python 3.3 has been removed. Support for Django 2.1 has been added, support for Django<1.11 is removed. Support for deprecated South has been removed.
Some updates have been made on the documentation such as:
Misc updates in the docs (formatting)
Added italian translation
Remove unnecessary db_index=True from doc examples
Include on_delete in all TreeForeignKey examples in docs
Use https:// URLs throughout docs where available
Document project as stable and ready for use in production
Add an example of add_related_count usage with the admin
Updates README.rst with svg badge
Update tutorial
Bug fixes:
Fix django-grappelli rendering bug (#661)
Fixing MPTT models (use explicit db)
Misc:
Update pypi.python.org URL to pypi.org
Remove redundant tox.ini options that respecify defaults
Remove unused argument from _inter_tree_move_and_close_gap()
Trim trailing white space throughout the project
Pass python_requires argument to setuptools
Added MpttConfig
Add test case to support ancestor coercion callbacks.
Extend tree_item_iterator with ancestor coercion callback.
Now supports django 1.11 and 2.0.
Now supports django 1.11 and 2.0.
Removed tests for unsupported django versions (django 1.9, 1.10)
Nothing published for this version
Now supports django 1.10. After upgrading, you may come across this error when running migrations::
Now supports django 1.10. After upgrading, you may come across this error when running migrations:
Unhandled exception in thread started by <function wrapper at 0x7f32e681faa0>
Traceback (most recent call last):
#...
File "venv/lib/python2.7/site-packages/django/db/models/manager.py", line 120, in contribute_to_class
setattr(model, name, ManagerDescriptor(self))
AttributeError: can't set attribute
To fix this, please replace ._default_manager in your historic migrations with .objects. For more detailed information see #469, #498
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Dropped support for old Django versions and Python 2.6 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Unsupported versions of django (1.4, 1.5, 1.6, 1.7) are no longer supported, and Python 2.6 is no longer supported.
These versions of python/django no longer receive security patches. You should upgrade to Python 2.7 and Django 1.8+.
Django 1.9 support has been added.
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Deprecated: Calling recursetree/cache_tree_children with incorrectly-ordered querysets ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~…
Django 1.5 support has been removed since django 1.5 is not supported upstream any longer.
Django 1.8 support has been added.
Previously, when given a queryset argument, cache_tree_children called .order_by to ensure that the queryset was in the correct order. In 0.7, calling cache_tree_children with an incorrectly-ordered queryset will cause a deprecation warning. In 0.8, it will raise an error.
This also applies to recursetree, since it calls cache_tree_children.
This probably doesn't affect many usages, since the default ordering for mptt models will work fine.
Django renamed get_query_set to get_queryset in Django 1.6. For backward compatibility django-mptt had both methods available for 1.4-1.5 users.
This has been removed. You should use get_query_set on Django 1.4-1.5, and get_queryset if you're on 1.6+.
Deprecated in 0.6.0, this has now been removed.
Nothing published for this version
Deprecated FeinCMSModelAdmin ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
mptt 0.6 drops support for both Python 2.4 and 2.5.
This was done to make it easier to support Python 3, as well as support the new context managers (delay_mptt_updates and disable_mptt_updates).
If you absolutely can't upgrade your Python version, you'll need to stick to mptt 0.5.5 until you can.
Until 0.5, TreeNodeChoiceField and TreeNodeMultipleChoiceField implicitly set empty_label=True. This was around since a long time ago, for unknown reasons. It has been removed in 0.6.0 as it caused occasional headaches for users.
If you were relying on this behavior, you'll need to explicitly pass empty_label=True to any of those fields you use, otherwise you will start seeing new '--------' choices appearing in them.
If you were using mptt.admin.FeinCMSModelAdmin, you should switch to using feincms.admin.tree_editor.TreeEditor instead, or you'll get a loud deprecation warning.
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
In 0.4, we deprecated all these attributes on model._meta. These have now been removed::
In 0.5, TreeManager now behaves just like a normal django manager. If you don't override anything, you'll now get a TreeManager by default (.objects.)
Before 0.5, .tree was the default name for the TreeManager. That's been removed, so we recommend updating your code to use .objects.
If you don't want to update .tree to .objects everywhere just yet, you should add an explicit TreeManager to your models:
objects = tree = TreeManager()
In earlier versions, MPTTModel.save() had a raw keyword argument. If True, the MPTT fields would not be updated during the save. This (undocumented) argument has now been removed.
In 0.4, we deprecated all these attributes on model._meta. These have now been removed:
MyModel._meta.left_attr MyModel._meta.right_attr MyModel._meta.tree_id_attr MyModel._meta.level_attr MyModel._meta.tree_manager_attr MyModel._meta.parent_attr MyModel._meta.order_insertion_by
If you're still using any of these, you'll need to update by simply renaming _meta to _mptt_meta.
Tests are now run with:
cd tests/ ./runtests.sh
The previous method (python setup.py test) no longer works since we switched to plain distutils.
Nothing published for this version
Nothing published for this version
Nothing published for this version
MPTT attributes on MyModel._meta deprecated, moved to MyModel._mptt_meta
Most people won't need to worry about this, but if you're using any of the following, note that these are deprecated and will be removed in 0.5:
MyModel._meta.left_attr MyModel._meta.right_attr MyModel._meta.tree_id_attr MyModel._meta.level_attr MyModel._meta.tree_manager_attr MyModel._meta.parent_attr MyModel._meta.order_insertion_by
They'll continue to work as previously for now, but you should upgrade your code if you can. Simply replace _meta with _mptt_meta.
The preferred way to do model registration in django-mptt 0.4 is via model inheritance.
Suppose you start with this:
class Node(models.Model):
...
mptt.register(Node, order_insertion_by=['name'], parent_attr='padre')
First, Make your model a subclass of MPTTModel, instead of models.Model:
from mptt.models import MPTTModel
class Node(MPTTModel):
...
Then remove your call to mptt.register(). If you were passing it keyword arguments, you should add them to an MPTTMeta inner class on the model:
class Node(MPTTModel):
...
class MPTTMeta:
order_insertion_by = ['name']
parent_attr = 'padre'
If necessary you can still use mptt.register. It was removed in 0.4.0 but restored in 0.4.2, since people reported use cases that didn't work without it.)
For instance, if you need to register models where the code isn't under your control, you'll need to use mptt.register().
Behind the scenes, mptt.register() in 0.4 will actually add MPTTModel to Node.__bases__, thus achieving the same result as subclassing MPTTModel. If you're already inheriting from something other than Model, that means multiple inheritance.
You're probably all upgraded at this point :) A couple more notes for more complex scenarios:
If your model is already a subclass of an abstract model, you should use multiple inheritance:
class Node(MPTTModel, ParentModel):
...
You should always put MPTTModel as the first model base. This is because there's some complicated metaclass stuff going on behind the scenes, and if Django's model metaclass gets called before the MPTT one, strange things can happen.
Isn't multiple inheritance evil? Well, maybe. However, the Django model docs don't forbid this, and as long as your other model doesn't have conflicting methods, it should be fine.
Note
As always when dealing with multiple inheritance, approach with a bit of caution.
Our brief testing says it works, but if you find that the Django internals are somehow breaking this approach for you, please create an issue with specifics.
MPTTModel was added in 0.4. If you're writing a library or reusable app that needs to work with 0.3, you should use the mptt.register() function instead, as above.
Nothing published for this version
Nothing published for this version
Nothing published for this version
One column per quarter.