🚀 SnapAdmin

Write your data model once. Get the admin panel, the REST API, the GraphQL endpoint and the search index — automatically.

📚 Documentation · 📦 Django Packages · 📝 Changelog · 🔒 Security · 🧭 llms.txt

Start where you are

Why this exists

Every internal tool needs the same four things: a screen where staff manage the data, an API for the mobile app, an API for the frontend team, and a search box. Today each one is written and maintained separately — four descriptions of the same data, four places to update when a field changes, four chances to leak a field you meant to keep private.

SnapAdmin generates all four from one description.

In one sentence for a decision maker: it turns weeks of internal-tool plumbing into a declaration your developers write once, and keeps the admin panel, the APIs and the search in sync automatically — so a field is defined in exactly one place.

What that buys you, concretely. The admin screen your ops team asks for on Friday is a keyword argument, not a sprint. A new field reaches the API, the search index and the audit log the moment it reaches the model — there is no second ticket, and no "we forgot to add it to the serializer" incident. And the fields you don't want exposed are excluded once, in the model, rather than re-excluded in every surface by whoever writes it next.

What it is not. It is not a theme, not a framework, and not a lock-in. Underneath it is ordinary Django — models, ModelAdmin, DRF viewsets. Override any generated piece, or stop using it, without rewriting your data layer. Your hand-written ModelAdmin classes are never replaced: SnapAdmin skips any model you registered yourself.

Proof it holds up

Adoption risk is the real question, so every answer below is something you can verify yourself rather than take on trust.

→ The full quality story, with the names of the test files, so a reviewer can read them.

For teams and enterprise

The questions a tech lead or a manager asks before approving a dependency:

python demo/manage.py seed_large            # 100,000 customers and orders
python demo/manage.py benchmark_list_view   # query count + wall time

Database sharding and replica routing

Outgrowing a single PostgreSQL or MySQL instance today usually means hand-rolling Django DATABASES and DATABASE_ROUTERS. SNAPADMIN_SHARDING replaces that with one settings dict, at two levels of effort — and is completely inert until you set ENABLED: True: no new DATABASES entry, no extra router, no query overhead for an install that ignores it.

# settings.py — the simple path: a flat list of DSNs, sliced automatically
SNAPADMIN_SHARDING = {
    "ENABLED": True,
    "SHARDING_ENABLED": True,    # partition data across shards
    "MIRRORING_ENABLED": True,   # give each shard read replicas
    "REPLICAS_PER_SHARD": 1,
    "DATABASES": [
        "postgres://user:pass@s1-primary:5432/db", "postgres://user:pass@s1-replica:5432/db",
        "postgres://user:pass@s2-primary:5432/db", "postgres://user:pass@s2-replica:5432/db",
    ],
}

Or name every shard's primary/replicas explicitly (SHARDS = {"shard_1": {"PRIMARY": ..., "REPLICAS": [...]}}) for full manual control, with STRATEGY picking how a row's shard is resolved — modulo, hash, range, or your own CUSTOM_ROUTER_FUNC.

A model opts in with shard_key — a field name, or True for the project-wide default — mirroring exactly how tenant_scoped opts a model into multi-tenancy above, so nothing (including Django's own auth/sessions/admin tables) is ever routed across shards without asking:

class Order(SnapModel):
    shard_key = "customer_id"

snap_master_only() / snap_target(shard="shard_2", replica=True) force routing for one block of code — both work as a context manager or a decorator, on a plain function or an async def one alike. manage.py snap_migrate migrates every shard's primary only (sequentially, or all at once with --parallel), and manage.py snapadmin_db_backup backs up every shard's primary too — neither command ever touches a replica. HA_SETTINGS controls failover (promote a live replica to serve writes when the primary is down) and fallback (read from the primary once every replica is down, or refuse outright if you'd rather protect the primary from that traffic). Full reference: Database sharding.

Getting started

Try it — 60 seconds, no setup

pip install django-snapadmin
snapadmin-new myshop
cd myshop
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

Open http://127.0.0.1:8000/admin/. The admin, the REST API (/api/docs/) and GraphQL (/api/graphql/) are already running against a working example model. SQLite, no Docker, nothing to edit by hand.

Just want to look around first? snapadmin-demo downloads a fully-loaded demo — search, audit trail, background jobs, the works. Log in at /admin/ with admin / admin.

Your first model — 3 steps

You add keyword arguments to your fields. They describe how the field should behave, and they add no database migration.

1. Declare the model.

# models.py
from snapadmin import fields as snap, models as snap_models

class Product(snap_models.SnapModel):
    name      = snap.SnapCharField(max_length=200, searchable=True, show_in_form=True)
    price     = snap.SnapDecimalField(max_digits=10, decimal_places=2, filterable=True, show_in_form=True)
    available = snap.SnapBooleanField(default=True, filterable=True, show_in_form=True)

    api_write_fields = ["name", "price", "available"]   # what an API client may set

2. Turn on the surfaces you want.

# settings.py
SNAPADMIN_REST_API_ENABLED = True    # off by default — you opt in
SNAPADMIN_GRAPHQL_ENABLED  = True    # same
SNAPADMIN_SWAGGER_ENABLED  = True

3. Register every model — one line.

# admin.py
from snapadmin.models import SnapModel
SnapModel.register_all_admins()

That is the whole setup. You now have:

┌────────────────────────────────────────────────────────────┐
│  SnapAdmin                           🔍 Search...    admin ▾│
├──────────────┬─────────────────────────────────────────────┤
│  SHOP        │  Products                         + Add     │
│  Categories  │ ┌──────────────────────────────────────────┐│
│  Products    │ │ Name            Price  In Stock  Category ││
│  Customers   │ │ Premium Laptop  $249   ● Active   Audio   ││
│  Orders      │ │ Ergonomic Mouse $89    ● Active   Access. ││
│  SYSTEM      │ │ USB-C Hub       $49    ○ Out      Electr. ││
│  Dashboard   │ └──────────────────────────────────────────┘│
└──────────────┴─────────────────────────────────────────────┘

The cheat sheet — the kwargs you'll actually use

Six keyword arguments cover most of what a new joiner needs on day one. None of them touch the database, so you can change your mind without a migration.

On the model itself:

More kwargs — tab / row layout, autocomplete, wysiwyg, upload validation — in the field reference. There are 30+ field types, from SnapCharField to SnapPhoneField, SnapColorField and SnapStatusBadgeField.

Already have models you cannot rewrite?

Subclassing SnapModel is the full route, and it is the natural choice for a new model. If your model layer already exists — a brownfield schema, a base class from a third-party package, fields from django-money or phonenumber_field — opt in from the outside instead. @snap_model adds no field and no attribute, so it needs no migration:

from django.db import models
from snapadmin import snap_model

@snap_model(
    api_write_fields=["name", "price"],   # what an API client may set
    api_exclude_fields=["cost_price"],    # never leaves the server
    search_fields=["name"],               # what ?search= matches on
)
class Product(models.Model):
    name       = models.CharField(max_length=200)
    price      = models.DecimalField(max_digits=10, decimal_places=2)
    cost_price = models.DecimalField(max_digits=10, decimal_places=2)

You get the REST API, the GraphQL schema, the offline endpoints, the system checks and the snapadmin-info inventory. You do not get the parts that need SnapModel's machinery — Elasticsearch mirroring, the retention purge, the generated admin — and those sweeps skip the model rather than half-work. The full comparison table says exactly which is which.

from django.db import models
from snapadmin.fields import snap_field

class Product(models.Model):
    name = snap_field(models.CharField(max_length=255), searchable=True, filterable=True)

→ Field types · SnapModel reference · @snap_model for plain models · snap_field() for one field · Mixing Snap & plain fields

The commands

snapadmin-new myshop --app-name storefront   # name the example app yourself
snapadmin-new myshop --full                  # + Dockerfile, compose, Postgres/Redis/ES

snapadmin-init --api --graphql               # also check the REST / GraphQL config

snapadmin-info --section features            # just the ✓/✗ capability checklist
snapadmin-info --health-check                # probes only; non-zero exit if one fails
snapadmin-info --json                        # the same report for CI / monitoring

snapadmin-license-check --critical-only      # only what blocks commercial use

Is your integration actually correct?

A runnable checklist — every row names the command that proves it, not just the thing to remember. snapadmin-init prints this itself, with a ✅/❌/⚠️ per row (⚠️ = needs a running project to check, never a false green):

→ Full checklist — Must work / Should be configured / Data safety / Optional, with a "why it matters" column.

What you get

🖥 Admin panel — list columns, search and filters derived from your fields · themed responsive UI · status badges, tabs, inlines, autocomplete · field-level change history · an offline mode that keeps a list usable with no connection

🔌 APIs — REST CRUD with Swagger and auto-derived filters · GraphQL with permissions on every traversed relation · API tokens hashed at rest · per-model and per-field guards for what may be read and written · @snap_action exposes a business operation — approve, refund, recalculate — as a permission-checked endpoint, not just CRUD

🔍 Search (optional) — Elasticsearch with the index mapping derived from your fields · ?search= routed to ES automatically, falling back to the database when ES is down · resumable bulk reindex

⚙️ Operations — audit trail · GDPR retention · PII masking · backups · error and health alerts to email, Slack, Discord, Teams or Telegram · structured logging · 10 languages

🧭 Operability — misconfiguration surfaces at startup as a Django system check (snapadmin.E0xx / W0xx), not as a mystery at request time · snapadmin-info reports what is switched on, what is actually in use, and what is unreachable · snapadmin-license-check answers the legal question in one command

Quality & compatibility

This is a package other people's products depend on, so the test suite is treated as part of the product rather than as developer hygiene. Concretely, on the current release:

• 4,300+ tests, run on every push.
• 100% line coverage on the shipped snapadmin/ package — 10,400+ statements, no exclusions, no # pragma: no cover to hide untested code. CI runs pytest --cov=snapadmin --cov-fail-under=100, so a pull request that adds an untested line fails.
• The full compatibility matrix on every push — Python 3.10 / 3.11 / 3.12 / 3.13 × Django 5.2 and 6.0. A release is gated on the same matrix: the tag-triggered publish workflow runs it before anything reaches PyPI.

Backward compatibility is a test, not a promise

These suites exist for one purpose only: to fail loudly when a public name, signature or default changes, so a breaking change is a deliberate decision rather than a side effect of a refactor.

Removing or renaming a public name is a major-version-only change under the API-stability policy; deprecations warn first and name their replacement.

The documentation is tested too

Docs rot silently: nothing breaks at import time when a section disappears or a setting is never written down, it just teaches the next reader something false. So the docs are asserted, not trusted:

Automated checks on the operator tooling

snapadmin-info is the command an operator runs to answer "is this configured correctly?" — so a false green there is worse than no report at all. 200+ tests across eleven files cover the diagnostics package, including 60+ in tests/test_diagnostics_features.py alone, where every capability probe in the readiness audit is exercised both switched on and switched off. A capability cannot ship without a probe, and a probe cannot ship without both tests.

The same standard applies to the rest of the operator surface: 150+ tests on the startup system checks, 60+ on the licence audit and its command, and full suites on the scaffolding (snapadmin-new), the read-only integrator (snapadmin-init) and the demo fetcher (snapadmin-demo).

An end-to-end tripwire

Every layer has its own deep suite — and each can keep passing while the seam between layers quietly breaks. tests/test_critical_path_smoke.py walks the whole declarative pipeline in one test: it posts the real generated admin add form, then asserts the row that comes out is the same one the REST API serves and the same one the audit trail recorded, with the acting user and a per-field diff. It is deliberately small — a tripwire for "the pipeline stopped connecting", not a second copy of the deep suites.

Roadmap — what's landing next

Encrypted model fields are on the near-term roadmap, listed here so you can plan around them — it has not shipped yet. It follows the same rule as everything else in the package: additive, opt-in, and completely inert until you configure it — an existing install that ignores it is byte-for-byte unaffected, with no new setting required and no migration from the package itself.

Declarative sharding and read-replica routing, previously listed here as in development, has shipped — see Database sharding and replica routing below.

Encrypted model fields · designed, next in the queue

Ciphertext in the database, plaintext in Python — a SnapEncryptedCharField family that encrypts transparently on write and decrypts on read, closing the gap that PII masking (render-time) and encrypted backups (whole-artefact) leave open: the column itself.

The design is already fixed, and it is deliberately conservative:

• AES-256-GCM only — one AEAD, a fresh random nonce per write, and the ciphertext bound to its own column so a value copied into another field fails to decrypt rather than silently moving a secret. Backed by cryptography (Apache-2.0/BSD) behind an optional [encryption] extra, so the base install stays permissive and dependency-free for projects that don't encrypt anything.
• A dedicated keyset, never SECRET_KEY — resolved from a KMS/Vault provider callable, a mounted secret file, an environment variable, or settings, in that order of preference, with startup checks that refuse the dangerous combinations.
• Fail closed — a missing key is a startup error, not a silent write of plaintext into a column that is supposed to be encrypted. An unreadable row raises, naming the missing key id and never the key.
• Zero-downtime key rotation, plus a management command to adopt existing plaintext columns and re-encrypt under a new key, batched, resumable and dry-run by default.
• No accidental plaintext downstream — encrypted fields are excluded from the Elasticsearch document by default, the audit log records that a value changed rather than what it changed to, and exports and API responses go through the existing per-field permission gate.
• Searchability, honestly — encryption makes icontains, ranges and ORDER BY impossible, so those raise a clear error rather than silently matching nothing. For exact match there is an opt-in blind index, with the equality leak it implies documented as plainly as the feature.

Follow the changelog for what has actually shipped.

Install

pip install django-snapadmin

Requires Python ≥ 3.10 and Django ≥ 5.2. Pin an exact version in production.

Adding it to an existing project? Run snapadmin-init. It inspects your project and prints a checklist plus the exact snippets to paste. It edits nothing, so there is nothing to undo.

INSTALLED_APPS = [
    # ── Django itself ───────────────────────────────────────────────────────
    "django.contrib.admin",          # SnapAdmin generates ModelAdmins into this site
    "django.contrib.auth",           # permissions gate both the admin and the API
    "django.contrib.contenttypes",   # required by auth; the audit trail keys off it
    "django.contrib.sessions",       # admin login
    "django.contrib.messages",       # admin "saved successfully" banners
    "django.contrib.staticfiles",    # serves SnapAdmin's CSS/JS

    # ── SnapAdmin ───────────────────────────────────────────────────────────
    "snapadmin",

    "myapp",                         # …your own apps
]

# urls.py
from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("admin/", admin.site.urls),
    path("api/", include("snapadmin.urls")),   # health check, and any surface you turn on
]

pip install "django-snapadmin[api,graphql]"   # or [api] alone, or [all]

INSTALLED_APPS = [
    ...,
    # ── The API stack — [api] + [graphql] extras ────────────────────────────
    "rest_framework",                # the generated REST endpoints are DRF viewsets
    "drf_spectacular",               # builds the OpenAPI schema behind /api/docs/
    "django_filters",                # backs the auto-generated ?field=… query filters
    "graphene_django",               # the generated GraphQL schema
    "snapadmin",
    ...,
]

# settings.py — the surfaces are opt-in
SNAPADMIN_REST_API_ENABLED = True
SNAPADMIN_GRAPHQL_ENABLED = True
SNAPADMIN_SWAGGER_ENABLED = True      # follows the REST setting unless set explicitly

INSTALLED_APPS = [
    # ── Themed UI — pip install django-snapadmin[theme] ─────────────────────
    # MUST come before django.contrib.admin: Unfold overrides admin templates,
    # and Django resolves templates in INSTALLED_APPS order.
    "unfold",
    "unfold.contrib.filters",        # the sidebar range/dropdown filters SnapAdmin generates
    "unfold.contrib.forms",          # themed form widgets
    "unfold.contrib.inlines",        # themed inline formsets

    # ── Rich text — pip install django-snapadmin[wysiwyg] ───────────────────
    # Only needed for wysiwyg=True / SnapRichTextField. Bundles CKEditor 5,
    # which is GPL-or-commercial — that is why it is not a core dependency.
    "django_ckeditor_5",

    # ── Django itself ───────────────────────────────────────────────────────
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",

    # ── REST API — pip install django-snapadmin[api] ────────────────────────
    # Needed only if you set SNAPADMIN_REST_API_ENABLED/SNAPADMIN_SWAGGER_ENABLED
    # to True — both default to False.
    "rest_framework",
    "drf_spectacular",
    "django_filters",

    # ── GraphQL — pip install django-snapadmin[graphql] ──────────────────────
    # Needed only with SNAPADMIN_GRAPHQL_ENABLED = True (default False). Independent of [api].
    "graphene_django",

    # ── SnapAdmin ───────────────────────────────────────────────────────────
    "snapadmin",

    # ── Background tasks — pip install django-snapadmin[celery] ─────────────
    # Needed for the GDPR purge, async exports, error digests and backups.
    "django_celery_beat",            # edit the schedule from the admin
    "django_celery_results",         # store task results in the database

    # ── Admin-editable settings — pip install django-snapadmin[extra-settings]
    # SnapAdmin does not use it; add it if you want a runtime key/value Setting
    # model in the admin (the demo shows the pattern).
    "extra_settings",

    # ── Autocomplete list filters — [autocomplete-filter] (LGPL) ────────────
    # For your own AutocompleteFilter admin filters; SnapAdmin core never imports it.
    "admin_auto_filters",

    "myapp",
]

Configuration

Every surface is a plain Django setting. Switching one off removes its routes entirely:

SNAPADMIN_REST_API_ENABLED       = True    # REST CRUD endpoints — off by default, opt in explicitly
SNAPADMIN_GRAPHQL_ENABLED        = True    # GraphQL endpoint — same, off by default
SNAPADMIN_SWAGGER_ENABLED        = True    # Swagger UI + ReDoc
SNAPADMIN_URL_PREFIX             = ""      # relocate the whole API surface
SNAPADMIN_CONNECTIVITY_ENABLED   = False   # admin-wide health poll + offline save-guard (opt-in)

The first two default to False — a plain-admin migration that never asked for an API doesn't get one by accident. Set them to True to serve REST and/or GraphQL.

Don't want to decide all ~110 of them? SNAPADMIN_PROFILE = "admin" (or "api" / "full") picks sane defaults for the handful that actually matter — an explicit setting always overrides it.

Misconfiguration shows up at startup as a Django system check (snapadmin.W0xx / E0xx), not as a mystery at request time.

→ Every setting, with defaults · SNAPADMIN_PROFILE presets

git clone https://github.com/drofji/django-snapadmin.git
cd django-snapadmin
cp demo/dist.env demo/.env
docker compose -f demo/docker-compose.yml up --build

Documentation

Working with an AI assistant? Two entry points ship for exactly that, and both are pinned by tests so they cannot drift from the code: the module map in the snapadmin package docstring (help(snapadmin) — no network needed) and llms.txt.

Upgrading from drofji-automatically-django-admin? See the migration guide.

Security

API tokens are hashed at rest, rich-text HTML is sanitized on write, GraphQL enforces permissions on every traversed relation, and PII masking covers both APIs. Report vulnerabilities privately — see SECURITY.md for the policy, the supported-versions row and the production-hardening checklist.

Contributing

See CONTRIBUTING.md. The suite lives at tests/ in the source repository and must stay green with 100% coverage on snapadmin/:

pytest

Regression tests for a specific reported issue live next to the subsystem they cover (e.g. tests/test_fields.py for a field validator, tests/test_pii_masking.py for masking) — if you hit a bug, check there before filing one that might already be covered.

License

MIT — see LICENSE.