django-tree-queries

What it is and what it does

django-tree-queries adds efficient tree querying to Django models using recursive common table expressions instead of materialized path or nested set approaches. It extends Django querysets with methods to add computed columns (tree_depth, tree_path, tree_ordering) and control sibling ordering. The package supports PostgreSQL, SQLite (3.8.3 or higher), MySQL (8.0 or higher), and MariaDB (10.2.2 or higher), with automatic optimization for simple queries that avoids creating intermediate rank tables.

The library enforces a minimal design: parent foreign keys must be named "parent", primary keys must be integer or UUID, and tree depth is correctly defined with root nodes at depth zero. It includes an abstract model class with built-in loop protection and a variant for automatic sibling position management. The approach trades configurability for simplicity and performance, avoiding the complexity and data redundancy of other tree libraries.

Use it for:

• Build category hierarchies or organizational charts where you need to fetch all ancestors or descendants of a node efficiently.
• Implement breadcrumb navigation or tree views that require depth-first ordering and path information for each node.
• Manage nested comment threads or forum structures with automatic depth calculation and sibling ordering.
• Query large hierarchical datasets while avoiding N+1 query problems through recursive common table expressions.
• Reorder sibling nodes in a tree without recalculating the entire structure using automatic position management.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Query hierarchical tree structures in Django models using recursive common table expressions, with support for PostgreSQL, SQLite, MySQL, and MariaDB.

Yes. The package is actively maintained, has no security vulnerabilities, installs with zero dependencies, and solves a real problem with a clean, opinionated design. It is suitable for any Django project needing hierarchical data queries on supported databases. The 50-level limit on MySQL/MariaDB is a documented trade-off; verify it fits your use case before committing.

Install

django-tree-queries on PyPI

pip install django-tree-queries

uv add django-tree-queries

poetry add django-tree-queries

Installing django-tree-queries

Before you install

Low friction install with no runtime dependencies. Actively maintained, with last commit on 2026-08-14 and 516 repository stars indicating stable community adoption.

License in practice

BSD-3-Clause permissive license allows commercial and private use with minimal restrictions; suitable for most projects.

Quickstart

pip install django-tree-queries

from django_tree_queries.models import TreeNode
import django.db.models as models

class Node(TreeNode):
    name = models.CharField(max_length=100)

nodes = Node.objects.with_tree_fields()
for node in nodes:
    print(node.tree_depth, node.tree_path)

Requires Django 3.2 or better and Python 3.8 or better; MySQL/MariaDB trees limited to 50 levels maximum; parent foreign key must be named 'parent'.

Verify before relying

• Whether the performance optimization for simple cases delivers measurable improvement in typical workloads.
• Real-world experience with the 50-level depth limit on MySQL/MariaDB and whether it affects common use cases.
• Support for integer and UUID primary keys only—whether this limitation affects your existing models.

Package facts

Evidence: django_tree_queries-0.24.0-py3-none-any.whl

Tags

More Software Development packages