fastapi-router-lazy

Lazy, on-demand loading of FastAPI routers.

Large FastAPI applications pay for every router at startup: importing the module, building each route's dependency graph and response model, generating its OpenAPI schema. fastapi-router-lazy mounts a tiny stub per route and loads the real router only on the first request matching one of its paths.

The full startup win — unused router modules are never imported — comes from generating the route metadata ahead of time and shipping it, so the app reads that cache at startup instead of importing every module. The default in-process extractor is the simplest wiring, but it imports each module at startup to read its routes: it mounts on demand without deferring the imports. The documentation covers which strategy defers imports.

The core needs nothing but FastAPI and works with plain fastapi.APIRouter.

Install

pip install fastapi-router-lazy
# variant/version-aware extraction:
pip install "fastapi-router-lazy[variants]"

Usage

The examples below use "myapp" as the name of your importable Python package — the one the extractor walks to find modules named router.py, each exposing an APIRouter:

myapp/                  # <- the package name you pass to route_infos_extractor
├── __init__.py
├── users/
│   └── router.py       # exposes `router = APIRouter()`
└── items/
    └── router.py

Given that layout, lazy loading is two steps.

1. Generate the route metadata (at build time — imports each module once and writes routes.json):

from pathlib import Path

from fastapi_router_lazy import route_infos_extractor

route_infos_extractor("myapp", cache=True, cache_file=Path("routes.json"))

2. Run lazily (at runtime — reads the metadata and imports no router module until its first matching request):

from pathlib import Path

from fastapi import FastAPI

from fastapi_router_lazy import (
    RouterLoader,
    lazy_middleware_factory,
    route_infos_extractor,
)

app = FastAPI()

# strict=True: use the prebuilt metadata, never re-import at startup.
extractor = route_infos_extractor(
    "myapp", cache=True, cache_file=Path("routes.json"), strict=True
)
loader = RouterLoader(extractor, app)

middleware = lazy_middleware_factory(loader)
app.add_middleware(middleware)

# Register the stubs; real routers load on first matching request.
loader.load(middleware)

The default extractor (route_infos_extractor("myapp"), no cache) is the simplest wiring, but it imports every module at startup to read its routes — it mounts on demand without deferring imports. Eager loading, deployment filtering, and the variant/version-aware extractor ([variants]) are covered in the documentation.

Limitations

Lazy loading trades some runtime dynamism for startup speed:

• lazily-declared routes are absent from /openapi.json and /docs until their first matching request mounts them (mount eagerly if you need a complete schema up front);
• no prefix= is applied at include_router time — bake prefixes into the APIRouter itself;
• a stub and a real route sharing a path are resolved by Starlette match order.

See the Limitations section of the docs for details.

Documentation

Full documentation is available at toilal.github.io/fastapi-router-lazy. A preview of the in-development develop branch is published at toilal.github.io/fastapi-router-lazy/dev/.

Requirements

Python 3.12+ and FastAPI.

License

MIT

CHANGELOG

v0.2.4 (2026-10-08)

Bug Fixes

• variants: Leave no child residue on parent RouterWrappers (#25, 5ffdcb9)

v0.2.3 (2026-10-08)

Bug Fixes

• Rebuild loaded routes from their effective include context (#23, 11f1c6a)

• extractor: Register routes reached through nested includes (#23, 11f1c6a)

• router-loader: Keep effective contexts off the caller's wrappers (#23, 11f1c6a)

• router-loader: Rebuild loaded routes from their effective include context (#23, 11f1c6a)

v0.2.2 (2026-07-25)

Bug Fixes

• router-loader: Isolate reparented routes (#20, b31933a)

• router-loader: Preserve dependency overrides (#20, b31933a)

v0.2.1 (2026-07-20)

Bug Fixes

• Flatten _IncludedRouter wrappers into serving routes (#18, 62b6788)

v0.2.0 (2026-07-05)

Features

• Support Python 3.11 (#16, ae5a84d)

v0.1.0 (2026-07-05)

• Initial Release

Changelog entries are generated automatically by python-semantic-release from Conventional Commits on release.