Registry / database / django-modelcluster

django-modelcluster

library6.5pypypi✓ verified 30d ago

django-modelcluster is a Django extension that allows working with 'clusters' of related models as a single unit, independently of the database. It introduces `ParentalKey` and `ClusterableModel` to enable in-memory manipulation of related objects, which is particularly useful for features like previews and revisions in content management systems like Wagtail. The current version is 6.4.1, and it maintains a consistent release schedule, often aligning with Django and Python version support.

database

pip install django-modelcluster

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · DJANGO-MODELCLUSTE

django-modelcluster

databasepythonv6.5

Install

3.4s avg

Import

—

Disk

66MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v6.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 66.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.4s · import 0.000s · 67MB

66MB installed

● package 66MB

Code

Verified usage

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

ClusterableModel

✓ from modelcluster.models import ClusterableModel

✗ from modelcluster.models import ClusterableModel

This example demonstrates defining a `ClusterableModel` (Band) and a related model (`BandMember`) connected via `ParentalKey`. It shows how to create a cluster of related objects in memory and access them before saving them to the database.

from django.db import models from modelcluster.models import ClusterableModel from modelcluster.fields import ParentalKey class Band(ClusterableModel): name = models.CharField(max_length=255) def __str__(self): return self.name class BandMember(models.Model): band = ParentalKey( 'Band', related_name='members', on_delete=models.CASCADE ) name = models.CharField(max_length=255) def __str__(self): return self.name # Example usage (in a Django shell or view): beatles = Band(name='The Beatles') # Related objects can be assigned to the in-memory 'members' attribute beatles.members = [ BandMember(name='John Lennon'), BandMember(name='Paul McCartney'), BandMember(name='George Harrison'), BandMember(name='Ringo Starr'), ] # Accessing in-memory members (behaves like a QuerySet subset) print([member.name for member in beatles.members.all()]) # Output: ['John Lennon', 'Paul McCartney', 'George Harrison', 'Ringo Starr'] # To save the cluster and its members to the database: # beatles.save() # This would also save all associated BandMember instances via ParentalKey

Debug

Known issues

breakingIn `ClusterForm` (v6.0 and later), child formsets are no longer built by default if neither `formsets` nor `exclude_formsets` is specified in the Meta class. This changes previous behavior where all child relations would automatically get a formset.

fix

Explicitly define `formsets` or `exclude_formsets` within the `Meta` class of your `ClusterForm` to control which child relations have formsets.

affects: >=6.0

breaking`django-modelcluster` frequently drops support for older Django and Python versions. For example, v6.4 removed Django 3.2 and Python 3.8 support.

fix

Always check the release notes (`CHANGELOG.txt`) for version compatibility and ensure your `django-modelcluster` version aligns with your Django and Python environment.

affects: All versions

gotchaA `ParentalKey` field must point to a model that inherits from `ClusterableModel`. Failing to do so will result in a Django system check error.

fix

Ensure the model referenced by `ParentalKey` (e.g., the 'Band' in `ParentalKey('Band', ...)`) inherits `modelcluster.models.ClusterableModel`.

affects: All versions

gotchaUsing `related_name='+'` is not allowed on `ParentalKey` fields, as `ParentalKey` requires an accessor name for its internal mechanisms.

fix

Provide a meaningful `related_name` for all `ParentalKey` fields, or omit it to let Django infer one.

affects: All versions

gotchaWhile `django-modelcluster` provides a `QuerySet`-like API for in-memory child objects, it's a 'fake' QuerySet with limitations. Advanced queryset operations (e.g., complex `order_by` traversals, `distinct()` before v6.3, or raw SQL queries) may not work as expected or are not supported on unsaved instances, particularly in contexts like content previews.

fix

Be aware of these limitations when querying in-memory relations. For complex logic, ensure the parent model and its children are saved, or adapt your code to work with lists/iterators where full queryset functionality isn't available.

affects: All versions

gotchaFor `ParentalManyToManyField`, only the *relationships* between the parent and the related objects are managed in memory. The *related objects themselves* (e.g., `Actor` instances in a `Movie.actors = ParentalManyToManyField(Actor)`) must already exist in the database before they can be associated in memory with the parent.

fix

Ensure that any objects intended to be related via `ParentalManyToManyField` are persisted to the database before attempting to establish the in-memory relationship with the parent `ClusterableModel`.

affects: All versions

Upgrade

Version history

6.5latest on PyPI · released May 1, 2026

Audit

Dependencies

DjangorequiredCore dependency as it's a Django extension.

django-taggitoptionalOften used with `ClusterTaggableManager` for tagging functionality in Wagtail contexts. Not strictly required for basic `django-modelcluster` usage.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/wagtail/django-modelcluster ↗

packagehttps://pypi.org/project/django-modelcluster/ ↗

changeloghttps://github.com/wagtail/django-modelcluster/blob/main/CHANGELOG.txt ↗