---
id: swapper
version: "1.4.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# swapper — The unofficial Django swappable models API.

License: permissive · Maintenance: active · Downloads: 522.8K/mo

## What it is and what it does

Swapper is a library that wraps Django's built-in but undocumented swappable models mechanism—the same system Django uses internally for auth.User—and exposes it as a stable API for third-party library authors. It lets you design reusable Django apps whose core models can be replaced entirely by end users, without forcing you to use abstract base classes or accept concrete models that cannot be customized.

The library provides functions to declare which models are swappable, load the correct model class at runtime (whether default or user-provided), and handle foreign keys and migrations correctly. This is primarily a tool for library authors; end users of your app typically configure a single setting to swap models, similar to how they would set AUTH_USER_MODEL.

Use it for:

- Building a reusable Django package where users need to extend or replace core models with custom fields or logic.
- Implementing multi-tenant or white-label SaaS applications where each tenant's model structure must be customizable.
- Creating extensible authentication or user management libraries that don't force a single User model design.
- Handling migration dependencies correctly when your library has multiple levels of related swappable models.
- Allowing end users to swap models without requiring them to fork or patch your library code.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Swapper provides an API for Django's undocumented swappable models feature, allowing library authors to make their app's models replaceable by end users without requiring abstract base classes or concrete model constraints.

Yes. Swapper is production-stable (Development Status 5), actively maintained, has no external dependencies, and solves a real problem for library authors building customizable Django apps. The MIT license imposes no restrictions. Install it if you are authoring a reusable Django package that needs model extensibility; skip it if you are building a single application.

## Install

pip install swapper
uv add swapper
poetry add swapper

## Installing swapper

Before you install: Low friction: pure Python wheel with no runtime dependencies. Actively maintained with recent commits and stable production status across Django 2.0 through 5.0.

License in practice: MIT license is permissive; you may use, modify, and distribute swapper freely in proprietary or open-source projects without restriction.

Quickstart:

pip install swapper

# In your reusable app's models.py:
import swapper

class Parent(models.Model):
    class Meta:
        swappable = swapper.swappable_setting('myapp', 'Parent')

# In views or other code:
Parent = swapper.load_model('myapp', 'Parent')

Requires Django to be installed and configured; swapper.load_model() should not be called until after Django's model system has fully initialized.

Verify before relying:

- Whether swapper works with Django versions earlier than 2.0 or later than 5.0 beyond what classifiers declare.
- Performance characteristics when swapping deeply nested model hierarchies with multiple foreign keys.

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: active
- Downloads: 522.8K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

django swappable models, django model customization, django model replacement, reusable django apps, django auth user pattern, django model inheritance, django app extensibility, django-extension, model-customization, library-authoring

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