swapper
The unofficial Django swappable models API.
Decision gist · record as of 2026-08-14
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.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires Django to be installed and configured; swapper.load_model() should not be called until after Django's model system has fully initialized.
- 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 · maintenance · safety
MIT (permissive) — MIT license is permissive; you may use, modify, and distribute swapper freely in proprietary or open-source projects without restriction.
last release 2024-08-14 (730 days) · last repo commit 2026-08-10 · 250 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 522,809 downloads/mo, #6,200 on PyPI
Alternatives
Verify before relying
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')- 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.
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 on this page. Verify before relying on it.
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
swapper on PyPI
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.
Requires Django to be installed and configured; swapper.load_model() should not be called until after Django's model system has fully initialized.
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')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 | Not specified |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | None |
| Maintenance | Actively maintained 730 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 522,809 / month, #6,200 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 :: DjangoFramework :: Django :: 2.0Framework :: Django :: 2.1Framework :: Django :: 2.2Framework :: Django :: 3.0Framework :: Django :: 3.1Framework :: Django :: 3.2Framework :: Django :: 4.0Framework :: Django :: 4.2Framework :: Django :: 5.0License :: OSI Approved :: MIT LicenseNatural Language :: EnglishOperating System :: OS IndependentProgramming Language :: Python :: 3Programming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.8Programming Language :: Python :: 3.9 |
Evidence: swapper-1.4.0-py2.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 swappable models”
- swapperSwapper provides an API for Django's undocumented swappable models…
- graphene-djangoGraphene-Django bridges Django models and GraphQL APIs, automatically…
- strawberry-graphql-djangoGenerates GraphQL types, queries, mutations, and resolvers…
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-reverse-admin · rest-framework-generic-relations · django-ordered-model · drf-writable-nested · django-model-utils · django-add-default-value · django-deprecate-fields · django-nonrelated-inlines · django-modelcluster · django-appconf