Admin

You pass every admin-wide setting as a keyword argument to the Admin class: the navbar title, the mount location, the CSRF and authentication configuration, and the rendered theme.

Basic usage

Start by importing the Admin class from the contrib package that matches your object-relational mapper (ORM):

from starlette_admin.contrib.sqla import Admin  # SQLAlchemy
from starlette_admin.contrib.sqlmodel import Admin  # SQLModel
from starlette_admin.contrib.beanie import Admin  # Beanie
from starlette_admin.contrib.mongoengine import Admin  # MongoEngine
from starlette_admin.contrib.tortoise import Admin  # Tortoise ORM

Here's a minimal configuration that uses SQLAlchemy:

from sqlalchemy import create_engine
from starlette.applications import Starlette
from starlette_admin.contrib.sqla import Admin, ModelView

from myapp.models import Post

engine = create_engine("sqlite:///admin.sqlite")
app = Starlette()

admin = Admin(
    session_provider=engine,
    title="My Admin",
    base_url="/admin",
    secret_key="a-long-random-string",
)
admin.add_view(ModelView(Post))
admin.mount_to(app)

title sets the navbar text and the HTML <title> tag.
base_url defines the path prefix where the admin is mounted.
secret_key signs the CSRF and flash cookies.
add_view registers a view, and mount_to builds the admin's routes and middleware before mounting them onto your application.

Every Admin class accepts all the configuration options described below, and some add backend-specific behavior:

contrib.sqla.Admin(session_provider, ...) takes an Engine, AsyncEngine, sessionmaker, or async_sessionmaker as its first positional argument and inserts DBSessionMiddleware for you. contrib.sqlmodel.Admin is the same class, re-exported. See SQLAlchemy and SQLModel.
contrib.beanie.Admin, contrib.mongoengine.Admin, and contrib.tortoise.Admin take no extra constructor arguments, because Beanie, MongoEngine, and Tortoise ORM manage their own connections outside the admin. mongoengine.Admin also registers a GridFS file-serving route in mount_to. See Beanie, MongoEngine, and Tortoise ORM.

Full reference

The Admin constructor accepts all the parameters below as keyword arguments.

Identity and branding

Parameter	Type	Default	Description
`title`	`str`	`"Admin"`	Navbar text and `<title>` tag.
`logo_url`	`str \| Callable[[Request], str \| None] \| None`	`None`	Logo shown in the navbar instead of `title`. Pass a plain URL, or a callable that resolves it per request, for example for per-tenant branding.
`login_logo_url`	`str \| Callable[[Request], str \| None] \| None`	`None`	Logo shown on the sign-in page instead of `logo_url`. Falls back to `logo_url` when unset.
`favicon_url`	`str \| Callable[[Request], str \| None] \| None`	`None`	Favicon `<link>` href.

logo_url, login_logo_url, and favicon_url each accept either a string or a (request) -> str | None callable. Use a callable when branding depends on the request, such as in a multi-tenant application or when you serve several hostnames:

def logo_for_tenant(request):
    return f"https://cdn.example.com/{request.state.tenant}/logo.png"


admin = Admin(engine, title="My Admin", logo_url=logo_for_tenant)

Mounting

Parameter	Type	Default	Description
`base_url`	`str`	`"/admin"`	URL prefix the admin is mounted under.
`route_name`	`str`	`"admin"`	Starlette mount name. Every internal link (`list`, `edit`, exports, static assets) is generated by calling `request.url_for(route_name + ":list", ...)`.

To run more than one Admin in the same application, give each instance a distinct base_url and route_name. Otherwise, links generated by one admin can resolve to another. See Multiple Admin Instances.

Templates, statics, and theme

Parameter	Type	Default	Description
`templates_dir`	`str`	`"templates"`	Directory checked for template overrides before falling back to the built-in templates.
`static_dir`	`str \| None`	`None`	Directory of extra static files served alongside the built-in CSS and JS.
`theme`	`BaseTheme`	`DefaultTheme()`	A theme subclass that defines the layout templates, icon set, and static assets.

Custom Themes and Templates cover these options in full.

The home page

Parameter	Type	Default	Description
`index_view`	`CustomView \| None`	`None` (a `DefaultIndexView` built from your registered views)	The page rendered at `base_url`.

The default home page is a welcome banner plus one panel per registered model view, each showing its record count. To replace it, pass your own CustomView, typically a DefaultIndexView subclass or any CustomView with a widget. See Custom Views & Widgets.

Auth, security, and data safety

Parameter	Type	Default	Description
`auth_provider`	`BaseAuthProvider \| None`	`None` (admin is publicly accessible)	Gates every route. See Authentication.
`secret_key`	`str \| None`	`None` (a random key is generated at startup, with a `UserWarning`)	Signs the CSRF and flash cookies.
`middlewares`	`Sequence[Middleware] \| None`	`None`	Extra Starlette middleware, run in addition to the CSRF, flash, and auth middleware the admin adds itself.
`import_config`	`ImportConfig \| None`	`None` (`ImportConfig()` defaults)	Upload size and ZIP-bomb limits for the import endpoint.
`export_config`	`ExportConfig \| None`	`None` (`ExportConfig()` defaults)	Row-count cap and URL-file download limits for the export endpoint.

The Security guide covers all five parameters in depth.

Locale and timezone

Parameter	Type	Default	Description
`i18n_config`	`I18nConfig \| None`	`None` (English only, no `LocaleMiddleware`)	Enables translated UI strings.
`timezone_config`	`TimezoneConfig \| None`	`TimezoneConfig()` (on)	Converts displayed datetimes to the viewer's timezone.

For a complete walkthrough, see Internationalization & Timezones.

Debugging

Parameter	Type	Default	Description
`debug`	`bool`	`False`	When `True`, calls `starlette_admin.logging.configure_logging()` before startup, which turns on colored DEBUG-level console logging for the `starlette_admin` package.

admin = Admin(
    session_provider=engine, title="My Admin", secret_key="a-long-random-string", debug=True
)

Debug logging helps during development. Every request logs the middleware that ran, the view that resolved the URL, and the reason a permission check passed or failed.

Warning

Keep debug=False in production. DEBUG-level logging is verbose and adds significant overhead to every request.

For a lighter approach, call starlette_admin.logging.configure_logging(level=logging.INFO) yourself instead of passing debug=True. You get the handler without the full DEBUG verbosity.

Registering views and mounting

After you create the Admin instance, register your views and mount the admin to your application.

admin.add_view(ModelView(Post))  # Register a view (BaseModelView, CustomView, and so on)
admin.mount_to(app)  # Mount the admin onto your Starlette or FastAPI app

Registering views

Use add_view to add components to your admin dashboard. The method accepts either a view instance or a view class, and you can register model views, custom pages, dropdown menus, and external links.

Mounting the application

After you register all your views, call mount_to(app) exactly once to attach the admin to your Starlette or FastAPI application. This step finalizes the routing and security configuration.

Order of operations matters

Mounting locks the admin configuration so that every view is routed correctly.

Accessing admin.app before mounting raises a RuntimeError.
Registering another view or calling mount_to again after the first mount also raises a RuntimeError.

admin.app  # Raises RuntimeError: not mounted yet

admin.mount_to(app)
admin.app  # Returns the mounted sub-application

admin.add_view(ModelView(Comment))  # Raises RuntimeError: already mounted

What's next

Security: The secret_key, CSRF, and the export and import limits.
Authentication: Wiring up the auth_provider.
Multiple Admin Instances: Running more than one Admin in the same application.