django-modelcluster
Django extension to allow working with 'clusters' of models as a single unit, independently of the database
Decision gist · record as of 2026-08-14
Yes. django-modelcluster is actively maintained, has no known vulnerabilities, carries a permissive license, and solves a real Django limitation with low install friction. It is well-suited for any Django project that needs to work with unsaved model clusters or draft states. The only caveat is verifying that your specific ORM patterns (beyond basic QuerySet operations) are supported.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires Django as a runtime dependency and Python >= 3.10.
- Low friction: pure Python wheel with only django as a runtime dependency.
- Actively maintained with recent releases; repo shows 521 stars and current Python version support (3.10–3.14).
License · maintenance · safety
BSD-3-Clause (permissive) — BSD-3-Clause (permissive): you may use, modify, and distribute this package freely in commercial and private projects, provided you include the license text and do not hold the authors liable.
last release 2026-05-01 (105 days) · last repo commit 2026-05-01 · 521 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 1,007,619 downloads/mo, #4,521 on PyPI
Alternatives
Verify before relying
pip install django-modelcluster
from modelcluster.models import ClusterableModel
from modelcluster.fields import ParentalKey
class Band(ClusterableModel):
name = models.CharField(max_length=255)
class BandMember(models.Model):
band = ParentalKey('Band', related_name='members', on_delete=models.CASCADE)
name = models.CharField(max_length=255)
beatles = Band(name='The Beatles')
beatles.members = [BandMember(name='John Lennon')]
print(beatles.members.count()) # 1, before save
beatles.save() # now written to database- Performance characteristics when working with large clusters of related objects in memory.
- Compatibility with Django ORM features beyond the documented QuerySet subset (e.g., aggregations, annotations).
- Whether ParentalManyToManyField supports batch operations or only single-object assignment.
What it is and what it does
django-modelcluster solves the problem of working with related Django model objects before they exist in the database. Normally, Django foreign keys require both the parent and child records to be saved first; this package introduces ParentalKey and ParentalManyToManyField to hold related objects in memory until the parent is explicitly saved. This is useful for rendering previews of unsaved data, building draft model hierarchies, handling multi-step workflows, or constructing temporary object graphs for serialization or external systems.
The package extends ClusterableModel as the parent and uses ParentalKey in place of ForeignKey for one-to-many relations, and ParentalManyToManyField for many-to-many relations. Related objects are accessible via a subset of Django's QuerySet API (count, all, add) while in memory, and the entire cluster is persisted to the database in a single save() call. It also provides introspection functions to discover child relations on a model.
Use it for
- Render a preview of form data before the user confirms and saves the full model cluster to the database.
- Build and manipulate a tree of draft models in a multi-step workflow without intermediate database writes.
- Construct a temporary cluster of related objects, serialize it to JSON or another format, and send it to an external system.
- Create a deep copy of a model and all its child relations using get_all_child_relations introspection.
- Handle versioning or revision workflows where models exist in an incomplete state for extended periods.
Worth the install?
AI-flagged interpretation of the facts on this page. Verify before relying on it.
Yes.
django-modelcluster is actively maintained, has no known vulnerabilities, carries a permissive license, and solves a real Django limitation with low install friction. It is well-suited for any Django project that needs to work with unsaved model clusters or draft states. The only caveat is verifying that your specific ORM patterns (beyond basic QuerySet operations) are supported.
Install
django-modelcluster on PyPI
Before you install
Low friction: pure Python wheel with only django as a runtime dependency. Actively maintained with recent releases; repo shows 521 stars and current Python version support (3.10–3.14).
Requires Django as a runtime dependency and Python >= 3.10.
License in practice
BSD-3-Clause (permissive): you may use, modify, and distribute this package freely in commercial and private projects, provided you include the license text and do not hold the authors liable.
Quickstart
pip install django-modelcluster
from modelcluster.models import ClusterableModel
from modelcluster.fields import ParentalKey
class Band(ClusterableModel):
name = models.CharField(max_length=255)
class BandMember(models.Model):
band = ParentalKey('Band', related_name='members', on_delete=models.CASCADE)
name = models.CharField(max_length=255)
beatles = Band(name='The Beatles')
beatles.members = [BandMember(name='John Lennon')]
print(beatles.members.count()) # 1, before save
beatles.save() # now written to databaseVerify before relying
- Performance characteristics when working with large clusters of related objects in memory.
- Compatibility with Django ORM features beyond the documented QuerySet subset (e.g., aggregations, annotations).
- Whether ParentalManyToManyField supports batch operations or only single-object assignment.
Package facts
| License | BSD-3-Clause permissive |
| Python support | Supports the current Python release >=3.10 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 1 packagedjango |
| Maintenance | Actively maintained 105 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 1,007,619 / month, #4,521 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 5 - Production/StableEnvironment :: Web EnvironmentFramework :: DjangoIntended Audience :: DevelopersOperating System :: OS IndependentProgramming Language :: PythonProgramming Language :: Python :: 3 :: OnlyProgramming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.14 |
Evidence: django_modelcluster-6.5-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “django in-memory model relations”
- django-modelclusterdjango-modelcluster extends Django models to work with clusters of…
- rest-framework-generic-relationsProvides Django REST Framework serializers that handle Django's…
- drf-writable-nestedExtends Django REST Framework serializers to handle creation and…
Give your agent the search over MCP, or paste the wish link into any chat.
More Application Frameworks packages
FastAPI is a Python web framework for building REST APIs using type hints, with automatic request validation, serialization, and interactive API documentation.
Provides a way to document function parameters, class attributes, return types, and variables inline using Python's `Annotated` type hint syntax instead of traditional docstrings.
Textual is a Python framework for building cross-platform user interfaces that run in the terminal or web browser using a modern, component-based API.
Install it if you're developing CLI tools, dashboards, or interactive terminal applications.
Typer builds command-line applications from Python functions using type hints, automatically generating help text, argument parsing, and shell completion.
Install it if you are building CLIs in Python.
Build and connect to Model Context Protocol servers that expose tools, resources, and prompts to LLM applications over stdio, HTTP, or SSE transports.
Install it if you need to build or connect to servers.
Werkzeug is a WSGI utility library providing request/response objects, URL routing, an interactive debugger, HTTP utilities, and a development server for building web applications.
See also django-solo · drf-writable-nested · django-ordered-model · rest-framework-generic-relations · django-reverse-admin · django-tree-queries · django-sortedm2m · django-nonrelated-inlines · django-soft-delete · django-rest-polymorphic