Skip to content

Getting started

Install

pip install hxadmin            # CSV export included
pip install 'hxadmin[xlsx]'    # adds Excel export (XlsxWriter)

hxadmin needs Python 3.13+, FastAPI and SQLAlchemy 2.0+ with an async driver (asyncpg, aiosqlite, ...).

The models in these docs

The examples throughout these docs use the same three models, a small task tracker. They are the repository's demo models plus a few columns (active, is_superuser, archived) and a PasswordReset table that later examples need:

# myapp/models.py
import enum
from datetime import date, datetime

from sqlalchemy import Column, DateTime, ForeignKey, Table
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship


class Base(DeclarativeBase):
    pass


project_members = Table(
    "project_members",
    Base.metadata,
    Column("project_id", ForeignKey("projects.id"), primary_key=True),
    Column("user_id", ForeignKey("users.id"), primary_key=True),
)


class TaskStatus(enum.StrEnum):
    todo = "todo"
    doing = "doing"
    done = "done"


class User(Base):
    __tablename__ = "users"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str]
    email: Mapped[str] = mapped_column(unique=True)
    active: Mapped[bool] = mapped_column(default=True)
    is_superuser: Mapped[bool] = mapped_column(default=False)
    password_hash: Mapped[str | None]
    projects: Mapped[list["Project"]] = relationship(
        secondary=project_members, back_populates="members"
    )
    tasks: Mapped[list["Task"]] = relationship(back_populates="assignee")

    def __str__(self) -> str:
        return self.name


class Project(Base):
    __tablename__ = "projects"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str]
    description: Mapped[str | None]
    members: Mapped[list[User]] = relationship(secondary=project_members, back_populates="projects")
    tasks: Mapped[list["Task"]] = relationship(back_populates="project")

    def __str__(self) -> str:
        return self.name


class Task(Base):
    __tablename__ = "tasks"

    id: Mapped[int] = mapped_column(primary_key=True)
    title: Mapped[str]
    status: Mapped[TaskStatus] = mapped_column(default=TaskStatus.todo)
    priority: Mapped[int] = mapped_column(default=3)
    due_date: Mapped[date | None]
    archived: Mapped[bool] = mapped_column(default=False)
    project_id: Mapped[int] = mapped_column(ForeignKey("projects.id"))
    project: Mapped[Project] = relationship(back_populates="tasks")
    assignee_id: Mapped[int | None] = mapped_column(ForeignKey("users.id"))
    assignee: Mapped[User | None] = relationship(back_populates="tasks")

    def __str__(self) -> str:
        return self.title


class PasswordReset(Base):
    __tablename__ = "password_resets"

    id: Mapped[int] = mapped_column(primary_key=True)
    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"))
    token_hash: Mapped[str]
    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))

__str__ matters: it is what hxadmin shows for a row in titles, relation cells, comboboxes and toasts. Without it a row shows as User 3. See display in Views to change it per view instead.

A minimal admin

# myapp/main.py
from collections.abc import AsyncGenerator, AsyncIterator
from contextlib import asynccontextmanager

from fastapi import FastAPI
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine

from hxadmin import HxAdmin, ModelView
from myapp.models import Base, Project, Task, User

engine = create_async_engine("sqlite+aiosqlite:///app.db")
sessionmaker = async_sessionmaker(engine, expire_on_commit=False)


async def get_session() -> AsyncIterator[AsyncSession]:
    async with sessionmaker() as session:
        yield session


def current_admin_user() -> dict[str, str]:
    return {"name": "admin"}  # lets everyone in: replace before deploying, see below


@asynccontextmanager
async def lifespan(_: FastAPI) -> AsyncGenerator[None]:
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)
    yield
    await engine.dispose()


app = FastAPI(lifespan=lifespan)
admin = HxAdmin(app, session=get_session, auth=current_admin_user, title="My admin")


@admin.register
class UserView(ModelView[User]):
    model = User


@admin.register
class ProjectView(ModelView[Project]):
    model = Project


@admin.register
class TaskView(ModelView[Task]):
    model = Task

Run it with uvicorn myapp.main:app and open http://127.0.0.1:8000/admin/. The lifespan only creates the tables so the example starts on an empty database; a real project runs its migrations (Alembic, ...) instead.

The admin is mounted at prefix (default /admin). The dashboard lists every registered view with its row count, grouped under a heading per category; a category holding a single view joins the ungrouped cards, labelled with its category, instead of heading one card.

The auth above lets anyone in

current_admin_user returns a fixed user for every request, so anyone who can reach /admin/ can read, edit and delete every row. It is fine on your own machine. Before the admin is reachable by anyone else, replace it with a dependency that checks who is asking; Auth and sessions has a complete example.

session and auth are ordinary FastAPI dependencies; see Auth and sessions.

Branding

Pass logo_url for an image in the sidebar brand block:

admin = HxAdmin(
    app, session=get_session, auth=current_admin_user, title="My admin", logo_url="/static/logo.svg"
)

The URL is used as given, so it must be served by your app (for example with FastAPI's StaticFiles) or come from elsewhere. Without it, the brand block shows the title's first letter in an accent tile.

The demo

The repository ships a small todo app that exercises every feature:

make demo  # or: uv run --group demo python -m demos.orm

Then open http://127.0.0.1:8001/admin/. The demo creates and seeds demos/orm/demo.db on first start. Sign in as ada@example.com with the password demo. make demo/tables runs a second demo built on plain Core Tables (http://127.0.0.1:8002/admin/, admin@example.com / demo).