Litestar Cheat Sheet

1Install & app2.24

pip install "litestar[standard]"★
The standard extra bundles uvicorn, the CLI, and templating. Plain litestar is the minimal core.
from litestar import Litestar, get @get("/") async def hello() -> dict[str, str]: return {"hello": "world"} app = Litestar(route_handlers=[hello])★
The whole app. Register handlers on Litestar(route_handlers=[...]). The return annotation drives serialization and the OpenAPI schema.
litestar run --reload # dev server (finds app.py:app) litestar routes · litestar version★
Built-in CLI. It auto-discovers app in app.py; otherwise set --app module:app or LITESTAR_APP.

2Route handlers & params@get @post @put ...

from litestar import get, post, put, patch, delete★
One decorator per HTTP method — each is an async handler by default. (A sync handler needs @get(..., sync_to_thread=True).)
@get("/users/{user_id:int}") async def get_user(user_id: int) -> User: ...★
Path params declare a type in the path ({user_id:int}) and appear as a matching typed argument — parsed & validated.
@get("/search") async def search(q: str, limit: int = 10) -> list[Hit]: ...★
Query params = handler args not in the path. Defaults make them optional; Parameter(...) adds constraints/aliases/headers/cookies.

3Body & validationdata: Model

from msgspec import Struct class User(Struct): name: str age: int★
msgspec Struct is the fastest model — Litestar uses msgspec for validation/serialization. Dataclasses, TypedDict, Pydantic v1/v2, and attrs also work.
@post("/users") async def create(data: User) -> User: return data★
Annotate a param with a model and it's parsed from the JSON body — automatic validation, a 400 on bad input, zero boilerplate. The conventional name is data.
async def upload(data: bytes = Body(media_type=RequestEncodingType.MULTI_PART)): ...
Use Body(...) for form/multipart/URL-encoded bodies and to tune the media type.

4Controllers & routersgroup routes

from litestar import Controller, get, post class UserController(Controller): path = "/users" @get() async def list(self) -> list[User]: ... @post() async def create(self, data: User) -> User: ...★
Class-based grouping under a shared path. Handler paths are relative to it.
from litestar import Router api = Router(path="/api/v1", route_handlers=[UserController]) app = Litestar(route_handlers=[api])★
Routers nest controllers/handlers under a prefix — compose app → router → controller → handler.
# deps, guards, middleware, and config layer at EVERY level
Layered architecture: set dependencies/guards/middleware on app, router, controller, or handler — inner layers override outer.

5Dependency injectionProvide()

from litestar.di import Provide async def get_db() -> AsyncSession: ... app = Litestar(dependencies={"db": Provide(get_db)})★
Register a provider at any layer, then inject it by matching the parameter name to the key.
@get("/me") async def me(db: AsyncSession, user: User) -> User: ...★
Ask for db / user and Litestar supplies them. Providers can depend on other providers, the request, and app state.
Provide(get_config, use_cache=True, sync_to_thread=False)
use_cache reuses the value within a request; providers may be sync or async.

6DTOsshape (de)serialization

from litestar.dto import DataclassDTO, DTOConfig class UserReadDTO(DataclassDTO[User]): config = DTOConfig(exclude={"password"})★
DTOs control which fields cross the wire — exclude secrets, rename, or make partial. Also MsgspecDTO, PydanticDTO, and the SQLAlchemy plugin's SQLAlchemyDTO.
@post("/users", dto=UserWriteDTO, return_dto=UserReadDTO) async def create(data: User) -> User: ...★
dto= governs the inbound body; return_dto= governs the outbound response — different views of the same model.
async def patch(data: DTOData[User]) -> User: return data.create_instance() # partial update
DTOData accepts a partial payload — ideal for PATCH; build/merge the instance yourself.

7Lifespan, state, pluginsapp lifecycle

app = Litestar( route_handlers=[...], on_startup=[connect_db], on_shutdown=[close_db])★
Startup/shutdown hooks for pools, clients, warmup. Or pass lifespan=[async_context_manager] for setup+teardown in one place.
app.state.settings = load_settings() async def h(state: State) -> ...: # inject app state★
app.state is a shared store; inject it as state: State or reach it via request.app.state.
from litestar.plugins.sqlalchemy import SQLAlchemyPlugin app = Litestar(plugins=[SQLAlchemyPlugin(...)])
Plugins add integrations — SQLAlchemy (Advanced Alchemy: sessions, repositories, DTOs), structlog, Prometheus, and more.

8OpenAPI, guards, testingdocs, auth, tests

from litestar.openapi import OpenAPIConfig Litestar(openapi_config=OpenAPIConfig(title="API", version="1.0"))★
OpenAPI is automatic — served at /schema with Swagger, ReDoc, Scalar, Stoplight, and RapiDoc UIs out of the box.
def auth_guard(connection, handler) -> None: if not connection.headers.get("authorization"): raise NotAuthorizedException() @get("/admin", guards=[auth_guard])★
Guards run before the handler for authorization — raise to reject. Layer them like everything else. CORS via cors_config=CORSConfig(...).
from litestar.testing import create_test_client with create_test_client([hello]) as client: assert client.get("/").status_code == 200★
First-class testing — create_test_client / TestClient (and AsyncTestClient) spin up the app in-process, no server needed.

!Common gotchasread before shipping

it's `litestar`, not `starlite`
Starlite was renamed to Litestar at 2.0. Old import starlite code and pre-2.0 tutorials won't work — use the litestar package.
annotate the return type
The return annotation drives serialization and the OpenAPI schema. Omit it and you lose the schema (and may mis-serialize). Always type handler returns.
sync handlers need sync_to_thread
Handlers are async by default. A blocking sync handler must set sync_to_thread=True (run in a threadpool) or you'll stall the event loop / get a warning.
type path params in the path
Declare {id:int} in the route string, not just id: int in the signature — the path converter needs the type.
DI matches by parameter name
A dependency keyed "db" injects into a parameter named db. A name mismatch means it's never injected (or an unexpected-kwarg error).
litestar run must find the app
The CLI looks for app in app.py/application.py. Otherwise pass --app path.to:app or set LITESTAR_APP.
register handlers everywhere in the tree
A handler only exists if it's reachable from Litestar(route_handlers=[...]) via routers/controllers. Forgetting to register = 404.

Litestar cheat sheet