django-modeltree

library1.0.0pypypi✓ verified 90d ago

A Django library for representing hierarchical data (tree structures) using a materialized path approach. Version 1.0.0, low release cadence (last updated 2021).

database

pip install django-modeltree

github ↗homepage ↗

INSTALL

IMPORT

SIG · DJANGO-MODELTREE

django-modeltree

databasepythonv1.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

ModelTree

✓ from modeltree import ModelTree

✗ from django_modeltree import ModelTree

The package name uses underscore but import is 'modeltree'

TreeForeignKey

✓ from modeltree import TreeForeignKey

✗ from modeltree.fields import TreeForeignKey

TreeForeignKey is directly in modeltree, not a submodule

Define a tree model by inheriting from ModelTree, then use create() with parent= for hierarchy.

from django.db import models from modeltree import ModelTree class Category(ModelTree): name = models.CharField(max_length=100) # Creating root and child root = Category.objects.create(name='Root') child = Category.objects.create(name='Child', parent=root) print(root.get_children()) # [child]

Debug

Known issues

breakingModelTree overrides save() – will break if you override save() in your subclass without calling super().

fix

Ensure custom save() calls super().save() to maintain path integrity.

affects: all

deprecatedThe get_descendants() method returns a flat queryset, not a tree; misleading for beginners.

fix

Use get_tree() to get hierarchical structure.

affects: all

gotchaModelTree uses a char field 'path' for materialized path; max depth is limited by path length (default 255 chars).

fix

Increase path_max_length in Meta if deep trees exceed default.

affects: all

gotchadelete() method also deletes all descendants by default; no confirmation.

fix

Override delete() or use .delete(keep_children=True) if partial removal needed.

affects: all

Errors

Common errors & fixes

AttributeError: 'ModelBase' object has no attribute 'path'

ModelTree's 'path' field is not defined until after first migration.

fix

Run python manage.py makemigrations and migrate after adding ModelTree subclass.

django.core.exceptions.FieldDoesNotExist: Category has no field named 'parent'

ModelTree uses a TreeForeignKey for parent but you tried to define parent as a plain ForeignKey.

fix

Use TreeForeignKey (from modeltree import TreeForeignKey) for the parent field.

OperationalError: (1170, "BLOB/TEXT column 'path' used in key specification without a key length")

MySQL does not allow TEXT columns as primary keys or indexes without key length.

fix

Set path_max_length to a value <= 255 in Meta, or use a CharField path explicitly.

Upgrade

Version history

1.0.0latest on PyPI · released Jan 15, 2026

Audit

Dependencies

DjangorequiredCore requirement for model tree functionality

Agent activity

10 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/thomst/django-modeltree ↗

homepagehttps://github.com/thomst/django-modeltree ↗