Coming from Django Admin

If you are coming from Django Admin, you will feel at home in starlette-admin. Both frameworks generate administrative interfaces using declarative, per-model configurations. Both support inline editing, batch actions, and per-request permissions.

The differences are primarily structural. Instead of requiring Django, starlette-admin runs on any ASGI application, supports multiple ORMs, and allows you to plug in your own authentication system rather than imposing a built-in user model.

This guide maps every major ModelAdmin concept to its starlette-admin equivalent alongside direct code comparisons.

Mental Model

Registering a Model

from django.contrib import admin
from .models import Post


@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    list_display = ["title", "published", "created_at"]
    search_fields = ["title", "content"]

from starlette_admin.contrib.sqla import Admin, ModelView


class PostView(ModelView):
    fields = ["id", "title", "content", "published", "created_at"]
    exclude_fields_from_list = ["content"]
    searchable_fields = ["title", "content"]


admin = Admin(engine, title="Blog Admin", secret_key="change-me")
admin.add_view(PostView(Post, icon="fa fa-newspaper"))
admin.mount_to(app)  # app is your FastAPI or Starlette instance

There are two key structural differences to notice here:

1. Unified field declaration: The fields attribute acts as the single source of truth for all pages. You then use exclude_fields_from_list, exclude_fields_from_detail, exclude_fields_from_create, and exclude_fields_from_edit to define per-page variations.
2. Database lifecycle ownership: The Admin instance owns the database engine, meaning views do not need a session explicitly passed to them.

List Page Options

Forms

Fieldsets Example

class PostAdmin(admin.ModelAdmin):
    fieldsets = [
        ("Content", {"fields": ["title", "body"]}),
        ("Publication", {"fields": ["published", "created_at"]}),
    ]

from starlette_admin import FieldsetWidget


class PostView(ModelView):
    fields = ["id", "title", "body", "published", "created_at"]
    form_layout = [
        FieldsetWidget(legend="Content", children=["title", "body"]),
        FieldsetWidget(legend="Publication", children=["published", "created_at"]),
    ]

The form_layout attribute offers significantly more flexibility than traditional fieldsets. You can easily build out tabs, responsive grids, and nested layouts. For more details, see Form Layout.

Inlines

class CommentInline(admin.TabularInline):
    model = Comment
    extra = 1


class ArticleAdmin(admin.ModelAdmin):
    inlines = [CommentInline]

from starlette_admin.contrib.sqla import InlineModelView, ModelView


class CommentInline(InlineModelView):
    model = Comment
    fields = ["author", "body"]


class ArticleView(ModelView):
    inlines = [CommentInline]

Foreign keys are auto-detected when unambiguous, and composite foreign keys are fully supported. See Inline Forms for advanced configurations.

Actions

@admin.action(description="Mark selected articles as published")
def make_published(modeladmin, request, queryset):
    queryset.update(published=True)


class ArticleAdmin(admin.ModelAdmin):
    actions = [make_published]

from starlette_admin import ActionSelection, action, flash


class ArticleView(ModelView):
    actions = ["make_published", "delete"]

    @action(
        name="make_published",
        text="Mark selected articles as published",
        confirmation="Publish the selected articles?",
    )
    async def make_published(
        self, request: Request, selection: ActionSelection
    ) -> None:
        for article in await selection.rows():
            article.published = True
        flash(request, "Articles published")

Unlike Django Admin, which passes a QuerySet, the starlette-admin handler receives an ActionSelection object. This object evaluates rows, primary keys, and active filters lazily. It also behaves consistently when a user chooses to "select all matching" records.

Furthermore, actions support custom HTML forms directly in the confirmation dialog, a feature that requires building an intermediate page in Django Admin. For per-row operations, starlette-admin provides @row_action and @link_row_action, which have no direct equivalent in Django Admin.

Permissions and Authentication

While Django Admin delegates heavily to django.contrib.auth, starlette-admin splits the problem into two distinct parts: an AuthProvider answers "who is this user," and per-view methods answer "what can they do."

Example of restricting deletion based on user roles:

class ArticleView(ModelView):
    def can_delete(self, request: Request) -> bool:
        return "admin" in request.state.admin_user.roles

Because every can_* method receives the request object, authorization decisions can dynamically evaluate the current user, HTTP headers, or any other request-specific data.

Save Hooks and Signals

Site-Wide Configuration

What You Gain by Switching

• End-to-end async architecture: Handlers, lifecycle hooks, and widget callbacks can all be asynchronous coroutines running on your existing event loop, side-by-side with your FastAPI endpoints.
• Database flexibility: The exact same admin skills and configurations apply whether you use SQLAlchemy, SQLModel, MongoDB (via MongoEngine or Beanie), or Tortoise ORM.
• Native export and import capabilities: Built-in support for CSV, JSON, and PDF, plus extended support for Excel and other formats via tablib. Export records instantly or safely import bulk data using a preview-first wizard that enforces strict row-level validation and supports optional primary key upserts. See Export and Import.
• Integrated dashboard widgets: Stat cards, ApexCharts, and layout grids compose easily into index pages and custom views. You do not need to hunt for an external theme package to build complex dashboards. See Custom Views and Widgets.
• Modern user interface: Uses Tabler (Bootstrap 5) to provide a polished UI that includes dark mode, column visibility toggles, and search highlighting by default.

What You Must Bring Yourself

• Custom user authentication: There is no bundled user model or predefined permission database. You must implement AuthProvider.authenticate() to read from whichever datastore your application already utilizes.
• Audit logging: starlette-admin does not generate an automatic LogEntry table. You will need to wire the event system to your own custom audit table.
• Model-level UI configurations: Django conveniences like model-level choices, verbose_name, and validators do not automatically transfer. You will need to declare these explicitly on the starlette-admin field definition (e.g., using EnumField, label=, and validators=).