Skip to content
Back to top
View this page
Edit this page

# django-polymorphic

django-polymorphic builds on top of the standard Django model inheritance. It makes using inherited models easier. When a query is made at the base model, the inherited model classes are returned.

When we store models that inherit from a `Project` model…

    >>> Project.objects.create(topic="Department Party")
    >>> ArtProject.objects.create(topic="Painting with Tim", artist="T. Turner")
    >>> ResearchProject.objects.create(topic="Swallow Aerodynamics", supervisor="Dr. Winter")

…and want to retrieve all our projects, the subclassed models are returned!

    >>> Project.objects.all()
    [ <Project:         id 1, topic "Department Party">,
      <ArtProject:      id 2, topic "Painting with Tim", artist "T. Turner">,
      <ResearchProject: id 3, topic "Swallow Aerodynamics", supervisor "Dr. Winter"> ]

Using vanilla Django, we get the base class objects, which is rarely what we wanted:

    >>> Project.objects.all()
    [ <Project: id 1, topic "Department Party">,
      <Project: id 2, topic "Painting with Tim">,
      <Project: id 3, topic "Swallow Aerodynamics"> ]

## Features

- Full admin integration.

- ORM integration:

  - Support for ForeignKey, ManyToManyField, OneToOneField descriptors.

  - Support for proxy models.

  - Filtering/ordering of inherited models (`ArtProject___artist`).

  - Filtering model types: `instance_of()` and `not_instance_of()`

  - Combining querysets of different models (`qs3 = qs1 | qs2`)

  - Support for custom user-defined managers.

- Formset support.

- Uses the minimum amount of queries needed to fetch the inherited models.

- Disabling polymorphic behavior when needed.

## Getting started

- Quickstart
  - Making Your Models Polymorphic
  - Using Polymorphic Models
- Admin Integration
  - Setup
  - Example
  - Filtering child types
  - Inline models
  - Internal details
- Performance Considerations
  - Iteration: Memory vs DB Round Trips
  - `ContentType` retrieval
- Integrations
  - django-guardian
  - django-extra-views
  - django-reversion

## Advanced topics

- Formsets
- Class Based Views
  - Step 1: Selecting the Type
  - Step 2: Displaying the Form
  - Using `extra_views`
- Migrating Existing Models
  - Filling the content type value
- Managers & Querysets
  - Using a Custom Manager
  - Manager Inheritance
  - Using a Custom Queryset Class
- Deletion
  - Deleting Children (upcasting)
- Advanced Features
  - Filtering for classes (equivalent to python’s `isinstance()`):
  - Polymorphic filtering (for fields in inherited classes)
  - Combining Querysets
  - ManyToManyField, ForeignKey, OneToOneField
  - Copying Polymorphic objects
  - Working with Fixtures
  - Using Third Party Models (without modifying them)
  - Non-Polymorphic Queries
  - About Queryset Methods
  - Using enhanced Q-objects in any Places
  - Nicely Displaying Polymorphic Querysets
  - Create Children from Parents (Downcasting)
  - Delete Children, Leaving Parents (Upcasting)
  - Restrictions & Caveats
- Changelog
  - v4.10.2 (2026-01-14)
  - v4.10.1 (2026-01-13)
  - v4.10.0 (2026-01-13)
  - v4.9.0 (2026-01-09)
  - v4.8.0 (2026-01-08)
  - v4.7.0 (2026-01-07)
  - v4.6.0 (2026-01-05)
  - v4.3.1, v4.4.2, v4.5.2 (2026-01-01)
  - v4.5.1 (2025-12-24)
  - v4.5.0 (2025-12-22)
  - v4.4.1 (2025-12-15)
  - v4.4.0 (2025-12-14)
  - v4.3.0 (2025-12-09)
  - v4.2.0 (2025-12-04)
  - v4.1.0 (2025-05-20)
  - v4.0.0 (2025-05-20)
  - v3.1.0 (2021-11-18)
  - v3.0.0 (2020-08-21)
  - v2.1.2 (2019-07-15)
  - v2.1.1 (2019-07-15)
  - v2.1 (2019-07-15)
  - v2.0.3 (2018-08-24)
  - v2.0.2 (2018-02-05)
  - v2.0.1 (2018-02-05)
  - v2.0.0 (2018-01-22)
  - v1.3.1 (2018-04-16)
  - v1.3.0 (2017-08-01)
  - v1.2.0 (2017-05-01)
  - v1.1.0 (2017-02-03)
  - v1.0.2 (2016-10-14)
  - v1.0.1 (2016-09-11)
  - v1.0.0 (2016-09-02)
  - v0.9.2 (2016-05-04)
  - v0.9.1 (2016-02-18)
  - v0.9.0 (2016-02-17)
  - v0.8.1 (2015-12-29)
  - v0.8.0 (2015-12-28)
  - v0.7.2 (2015-10-01)
  - v0.7.1 (2015-04-30)
  - v0.7.0 (2015-04-08)
  - v0.6.1 (2014-12-30)
  - v0.6.0 (2014-10-14)
  - v0.5.6 (2014-07-21)
  - v0.5.5 (2014-04-29)
  - v0.5.4 (2014-04-09)
  - v0.5.3 (2013-09-17)
  - v0.5.2 (2013-09-05)
  - v0.5.1 (2013-07-05)
  - v0.5.0 (2013-04-20)
  - v0.4.2 (2013-04-10)
  - v0.4.1 (2013-04-10)
  - v0.4.0 (2013-03-25)
  - v0.3.1 (2013-02-28)
  - v0.3.0 (2013-02-28)
  - v0.2.0 (2011-04-27)
  - V1.0 Release Candidate 1 (2011-01-24)
  - Renaming, refactoring, new maintainer (2011-12-20)
  - V1.0 Beta 2 (2010-11-11)
  - V1.0 Beta 1 (2010-10-18)
  - Beta Release (2010-2-22)
  - Beta Release (2010-2-4)
  - Beta Release (2010-1-30)
  - Beta Release (2010-1-29)
  - Beta Release (2010-1-28)
  - Beta Release (2010-1-26)
- API Documentation
  - polymorphic.admin
  - polymorphic.contrib
  - polymorphic.formsets
  - polymorphic.managers
  - polymorphic.models
  - polymorphic.deletion
  - polymorphic.query
  - polymorphic.showfields
  - polymorphic.templatetags
  - polymorphic.utils

# Indices and tables

- Index

- Module Index

- Search Page