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 request that triggers the loading of a router carries an x-fastapi-router-lazy-loading-router: <module>:<variable> header, so the application can log which request paid for the import (read it with Header(alias=LAZY_LOADING_ROUTER_HEADER)). The middleware strips any header of that name sent by the client, from every request. Pass header_name="x-myapp-loading-router" to lazy_middleware_factory to rename it, and response_header=True to also set it on the response — off by default, as it exposes internal module names to the client.

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.

Routers computing their routes

The cache checksums each router file. A router that computes its routes from data declared elsewhere — a loop over an imported constant, a registry filled by other modules, enum values — must list those modules in a module-level __route_sources__, so that changing any of them re-extracts the router:

from fastapi import APIRouter

__route_sources__ = ("myapp.config.meta", "myapp.dal.ids")

router = APIRouter()

The cache reads the declaration from the source, without importing the router. A declaration that is not a tuple or list of module names, or that names a module that cannot be found, is reported by a warning and its router is re-extracted on every start (outside strict mode).

The declaration is the developer's responsibility: nothing detects a router that should declare route sources and does not. verify_route_infos_cache extracts routers again and returns the routes on which the cache disagrees; run it in a test suite, on every router module, to catch a missing or incomplete declaration:

from fastapi_router_lazy import (
    CachedRouteInfosExtractor,
    route_infos_extractor,
    verify_route_infos_cache,
)


def test_route_infos_cache_is_up_to_date() -> None:
    extractor = route_infos_extractor("myapp", cache=True)
    assert isinstance(extractor, CachedRouteInfosExtractor)
    modules = list(extractor.scan_router_modules())
    assert verify_route_infos_cache(extractor, modules) == []

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.11+ and FastAPI.

License

MIT

CHANGELOG

v0.4.0 (2026-11-01)

Features

• cached-extractor: Checksum routers with their declared route sources (dd2013b)

v0.3.0 (2026-10-25)

Bug Fixes

• cached-extractor: Write the route infos cache atomically and survive a corrupted one (533ab0b)

• router-loader: Keep the streamed item type and deduplicate tags on flattened routes (5387fa4)

• variants: Extract variant route infos in a subprocess and resolve subclassed routers (108336e)

Features

• middleware: Set the lazy-loading header on the request, with a configurable name (98c2a6f)

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.