sqladmin

library0.31.0pypypi✓ verified 22d ago

SQLAdmin is a flexible and actively developed admin interface for SQLAlchemy models, designed for use with FastAPI and Starlette. It provides a UI for managing database models, leveraging WTForms for form building and Tabler for the UI. The library maintains a regular release cadence, with updates typically occurring every few weeks to a month.

web-framework database

pip install sqladmin

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · SQLADMIN

sqladmin

web-frameworkpythonv0.31.0

Install

4.3s avg

Import

1181ms

Disk

76MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.31.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 1.226s · 83.8MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 4.3s · import 1.135s · 82MB

76MB installed

● package 76MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Admin

✓ from sqladmin import Admin

ModelView

✓ from sqladmin import ModelView

AuthenticationBackend

✓ from sqladmin.authentication import AuthenticationBackend

✗ from sqladmin import AuthenticationBackend

AuthenticationBackend is in a submodule, not directly under sqladmin.

This quickstart demonstrates how to integrate SQLAdmin into a FastAPI application, defining a simple SQLAlchemy model and exposing it through the admin panel. It sets up an in-memory SQLite database and registers a `UserAdmin` view.

import os from fastapi import FastAPI from sqlalchemy import create_engine, Column, Integer, String from sqlalchemy.orm import declarative_base, sessionmaker from sqladmin import Admin, ModelView # 1. Database Setup DATABASE_URL = os.environ.get("DATABASE_URL", "sqlite:///./example.db") engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False}) Base = declarative_base() class User(Base): __tablename__ = "users" id = Column(Integer, primary_key=True) name = Column(String, default="Anonymous") email = Column(String, unique=True, nullable=False) Base.metadata.create_all(engine) # 2. FastAPI App Setup app = FastAPI(title="My SQLAdmin App") # 3. SQLAdmin Setup admin = Admin(app, engine, title="My Admin Panel") # 4. Define ModelView class UserAdmin(ModelView, model=User): column_list = [User.id, User.name, User.email] column_searchable_list = [User.name, User.email] column_sortable_list = [User.id, User.name, User.email] column_default_sort = ('id', True) # 5. Add ModelView to Admin admin.add_view(UserAdmin) @app.get("/") async def read_root(): return {"message": "Welcome! Visit /admin for the admin panel."} # To run this: # pip install fastapi uvicorn sqladmin sqlalchemy # uvicorn your_module_name:app --reload # Then navigate to http://127.0.0.1:8000/admin in your browser.

Debug

Known issues

gotchaSQLAdmin does not include authentication by default. For production environments, you must implement a custom `AuthenticationBackend` and integrate it with your ASGI application's middleware. Failing to do so will leave your admin panel publicly accessible.

fix

Implement a custom `AuthenticationBackend` by inheriting `sqladmin.authentication.AuthenticationBackend` and configure your ASGI app with an appropriate authentication middleware (e.g., Starlette's `AuthenticationMiddleware`). Refer to the official documentation for examples.

affects: All versions

breakingThe `AuthenticationBackend.authenticate` method signature has undergone breaking changes in versions 0.10.0 and 0.12.0. Custom authentication backends developed for older versions may require updates to match the new method signature (e.g., to support OAuth or updated `Request` object access).

fix

Review your custom `AuthenticationBackend` implementation and update the `authenticate` method signature and logic to align with the changes introduced in the respective versions. Consult the `CHANGELOG.md` or official documentation for the exact signature updates.

affects: 0.10.0, 0.12.0

breakingThe internal structure for template files changed around version 0.17.0, moving default templates from the `templates/` directory to `templates/sqladmin/`. If you have custom templates that override SQLAdmin's default ones, their paths may need adjustment.

fix

Ensure your custom template files are placed within a `templates/sqladmin/` directory in your project's root or a configured template search path. If you previously referred to `some_template.html`, you might now need to refer to `sqladmin/some_template.html` if overriding.

affects: >=0.17.0

gotchaWhen working with SQLAlchemy relationships, lazy-loaded relationships can cause `DetachedInstanceError` if accessed after the SQLAlchemy session has been closed. This is a common pitfall in ORM usage, especially in web contexts where sessions are typically short-lived.

fix

To prevent `DetachedInstanceError`, explicitly eager-load relationships using `selectinload` or include the related columns in `ModelView.column_list` or `ModelView.column_details_list` so that SQLAdmin fetches them within the active session. Ensure your `get_session` method manages the session lifecycle correctly.

affects: All versions

Errors

Common errors & fixes

TypeError: Model must be a SQLAlchemy model class

This error occurs when you attempt to register a class with ModelView that is not a valid SQLAlchemy declarative base model.

fix

Ensure that the class passed to ModelView inherits from a SQLAlchemy declarative base (e.g., your Base class or SQLAlchemyBaseUserMixin).

sqlalchemy.exc.OperationalError: (psycopg2.OperationalError) connection to server at "localhost" (::1), port 5432 failed: Connection refused

This error indicates that SQLAdmin, via SQLAlchemy, cannot establish a connection to the specified database server, often due to the database server not running, incorrect connection details, or network issues.

fix

Verify that your database server is running, check the connection string (DSN) for accuracy (host, port, user, password, database name), and confirm no firewall is blocking the connection.

ImportError: cannot import name 'AdminAuth' from 'sqladmin'

This error occurs when attempting to import `AdminAuth` directly from the top-level `sqladmin` package, but it resides in a specific submodule.

fix

Import `AdminAuth` from the `sqladmin.authentication` submodule.

TypeError: 'coroutine' object is not subscriptable

This error typically occurs when an asynchronous function (coroutine) is called but not `await`ed, leading to attempts to access its result synchronously, common with async SQLAlchemy engines.

fix

Ensure you `await` any asynchronous function calls (like `create_async_engine`) where their result is needed, especially when initializing the SQLAlchemy engine for SQLAdmin.

AttributeError: 'Admin' object has no attribute 'register_model'

This error occurs when attempting to use a method named `register_model` on the `Admin` instance, which does not exist in SQLAdmin.

fix

Use the correct method for registering SQLAlchemy models, which is `admin.add_view()` with a `ModelView` instance.

Upgrade

Version history

0.31.0latest on PyPI · released Aug 6, 2026

Audit

Dependencies

fastapirequiredCommon ASGI framework integration for building web applications.

starletterequiredCore ASGI framework integration, FastAPI builds on Starlette.

sqlalchemyrequiredPrimary ORM for database interaction.

wtformsrequiredUsed for generating forms within the admin interface.

sqlmodeloptionalSupport for SQLModel ORM models.

Agent activity

39 hits · last 30 days

node