Litestar Granian

Granian plugin for Litestar

Granian HTTP and WebSocket server plugin for Litestar applications.

Documentation · Quickstart · Configuration · Deployment · CLI Reference · Plugin API

litestar-granian runs Litestar applications on Granian's Rust HTTP/1, HTTP/2, and WebSocket runtime through the standard litestar run CLI. A supervised parent process manages server_lifespan hooks, forwards OS signals across the Granian worker group, bridges Litestar's active log formatters, and promotes static asset directories to Granian's native file server.

Install

uv add litestar-granian

Or with pip:

pip install litestar-granian

Install an optional event loop extra when needed (uvloop, rloop, or winloop):

uv add "litestar-granian[uvloop]"

Quickstart

Save as example.py:

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 litestar run:

litestar --app example:app run

Capabilities

Area	Overview
Drop-In `litestar run`	Replaces Litestar's `run` command with Granian's HTTP/1, HTTP/2, and WebSocket server while keeping `LITESTAR_*` flags and environment variables.
Process Supervision	Runs `server_lifespan` context managers once in the parent process and forwards `SIGINT`/`SIGTERM` cleanly across the Granian worker process group.
Log Formatter Bridge	Reconstructs Litestar's active standard, JSON, or `structlog` formatters inside Granian workers, or accepts an explicit `--log-config` override.
Native Static Files	Serves static asset directories directly from Granian via `--static-path-mount` or automatic `GranianPlugin(static="auto")` discovery.
Event Loops & Runtimes	Supports `asyncio`, `uvloop`, `rloop`, and `winloop` across Python 3.11–3.15, including free-threaded `3.14t` and `3.15t` builds.

Documentation

Getting Started & Quickstart — installation, first server run, and v0.16 migration notes.
Configuration & Runtime — bindings, workers, runtime threads, HTTP/2, reload, and event loops.
Logging & Metrics — automatic formatter matching, custom log configs, and Prometheus metrics.
Static Files — native Rust static asset mounts and SPA index rewrites.
Deployment & TLS — signal handling, container deployments, UNIX domain sockets, TLS, and mTLS.
API & CLI Reference — GranianPlugin API, litestar run CLI options, and compatibility notes.

Contributing & License

Contributions are welcome; see the Contribution Guide for local environment setup, testing, and release workflow. Distributed under the MIT License.