---
id: django-modelcluster
version: "6.5"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# django-modelcluster — Django extension to allow working with 'clusters' of models as a single unit, independently of the database

License: permissive · Maintenance: active · Downloads: 1.0M/mo

## 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 above — verify before relying.

django-modelcluster extends Django models to work with clusters of related objects in memory before saving to the database, using ParentalKey and ParentalManyToManyField relations.

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

pip install django-modelcluster
uv add django-modelcluster
poetry add django-modelcluster

## Installing django-modelcluster

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).

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 database

Requires Django as a runtime dependency and Python >= 3.10.

Verify 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_current
- Install friction: low
- Maintenance: active
- Downloads: 1.0M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

django in-memory model relations, django unsaved foreign key relations, django model clustering, django draft model state, django parentalkey alternative to foreignkey, django related objects without database, django model preview before save, django-extension, in-memory-relations, draft-state

[View on SkillFed](https://skillfed.io/packages/django-modelcluster) · [View on PyPI](https://pypi.org/project/django-modelcluster/)