Skip to content

Litestar Granian

Litestar Granian

Run Litestar applications on Granian while preserving Litestar server lifespans, signal supervision, logging formatters, and static asset serving.

Get Started Configuration Guide API & CLI Reference

Install

uv add litestar-granian

pip install litestar-granian

pdm add litestar-granian

poetry add litestar-granian

Minimal Example

Register GranianPlugin on your Litestar application:

from litestar import Litestar, get

from litestar_granian import GranianPlugin


@get("/")
async def hello() -> dict[str, str]:
    return {"hello": "world"}


app = Litestar(route_handlers=[hello], plugins=[GranianPlugin()])

Start the server with the standard litestar run command:

litestar --app docs.examples.app:app run

Explore Documentation

Section What You Will Find
Getting Started Installation, quickstart, v0.16 migration notes, contribution workflow, and release changelog.
Guides Runtime configuration, event loops, automatic formatter matching, Prometheus metrics, native static files, and production deployment.
Reference GranianPlugin API documentation, the generated litestar run CLI reference, and compatibility matrix.

Core Capabilities

Capability Summary
Drop-In litestar run Replaces litestar run with a Granian-backed server command while preserving standard Litestar flags and LITESTAR_* environment variables.
Supervised Process Group The Litestar parent process enters server_lifespan context managers once and supervises a Granian child process group with deterministic signal forwarding.
Automatic Formatter Matching Reconstructs Litestar's active standard, JSON, or structlog formatter inside Granian workers without coupling parent handlers or queues across processes.
Rust Static File Serving Serves static asset directories directly from Granian via --static-path-mount or GranianPlugin(static="auto") provider discovery.
Free-Threaded Python Ready Tested across Python 3.11–3.15 including free-threaded 3.14t and 3.15t builds with asyncio, uvloop, rloop, and winloop.

Runtime Architecture

When litestar run starts, the Litestar parent process enters application server_lifespan hooks once, prepares a temporary mode-0600 logging configuration if a compatible formatter is active, and spawns a supervised Granian worker group:

flowchart LR
    CLI["litestar run CLI"] --> Parent["Litestar Parent (server_lifespan & Signal Forwarder)"]
    Parent --> LogCfg["Formatter Bridge (Mode-0600 Log Config)"]
    Parent --> Granian["Granian Supervisor Process Group"]
    Granian --> Workers["Rust HTTP/1, HTTP/2 & WebSocket Workers"]
    Workers --> App["Litestar ASGI Application"]