How it works¶
patch_fastapi_deps_cache() replaces up to three functions in
fastapi.dependencies.utils (plus the fastapi.routing and
fastapi.openapi.utils re-imports) with caching wrappers backed by a
DepsCache. unpatch_fastapi_deps_cache() restores the
originals.
The cached functions¶
FastAPI introspects every route's dependency tree at startup with no caching. Shared dependencies (an auth check, a DB handle, a role guard …) are re-introspected from scratch for every route that uses them. The functions on that hot path, and how each is keyed:
| Function | Cache key | Why |
|---|---|---|
get_typed_signature |
id(call) |
avoid repeated signature parsing |
get_dependant |
(id(call), path params, name, use_cache, scope kwargs) |
avoid redundant tree introspection |
get_flat_dependant (FastAPI ≤ 0.140) |
(id(dependant), parent_oauth_scopes) |
the dominant startup cost on those versions |
On FastAPI ≤ 0.140, get_flat_dependant is the dominant cost: FastAPI calls it
once per route in APIRoute.__init__ to flatten the dependency tree, recursing
through every sub-dependency without caching. Caching the recursive results
turns O(routes × tree-depth) into O(routes + unique-deps).
FastAPI 0.141 removed get_flat_dependant: it now flattens the tree with
iterative walks that build no Dependant, so only get_typed_signature and
get_dependant are cached there.
Where the patch is applied¶
Each function is patched in every module that holds its own reference:
get_typed_signature— patched infastapi.dependencies.utilsonly (that is the sole caller).get_dependant— patched infastapi.dependencies.utils(for the recursive calls) and infastapi.routing(which imports its own reference).get_flat_dependant— patched infastapi.dependencies.utils(self-recursive calls),fastapi.openapi.utilsandfastapi.routing, but only in the modules that actually define it; the patched modules are remembered and restored on unpatch. Nothing is patched from FastAPI 0.141, where the function no longer exists: no attribute is ever injected into a FastAPI module.
The openapi.utils patch is effectively a no-op: both call sites there pass
skip_repeats=True, which the wrapper short-circuits straight to the original
without caching. It is installed for symmetry and as a safety net.
Copy-on-return semantics¶
Some Dependant list fields are mutated by FastAPI after introspection
returns (route-level parameterless dependencies inserted during routing, and on
FastAPI < 0.121 security_requirements). Handing back the shared cached object
would leak one route's mutations into every sibling that reuses the same cached
entry.
To stay safe, the wrappers shallow-copy the returned Dependant and give it
private copies of the mutated list containers:
get_flat_dependantresults are shallow-copied on the way out, with private copies ofpath_params,query_params,header_params,cookie_params,body_paramsanddependencies.get_dependantcopies the mutated fields (dependencies,security_requirements) only for the top-level path-operation dependant (name is None), which FastAPI mutates in place. Named sub-dependants are never mutated and keep their cached identity — that identity is what makes the recursive sub-dependency sharing work.
Only the list containers are private; their elements (ModelField and
sub-Dependant objects) remain shared references. Appending to or reordering a
returned list is safe; mutating an element in place is not.
Cache-key subtleties¶
get_dependantfolds in only the path param names, not the literal path string. Two routes with the same param names but different literals (/a/{id}vs/b/{id}) deliberately share one cachedDependant— this is what makes cross-route sharing effective. A consequence is that the shared object's.pathreflects whichever route populated it first; FastAPI reads.pathonly for diagnostics, never for routing, so the staleness is cosmetic.- The scope-related keyword arguments of
get_dependantandget_flat_dependantchanged across FastAPI versions. They are captured generically via**kwargsand folded into the key, so the wrappers stay compatible across the supported FastAPI range. - Calls with
skip_repeats=True(OpenAPI generation) bypass the cache since they depend on a mutablevisitedlist, and are not a startup bottleneck anyway.
id() recycling protection¶
The signature and dependant caches key on id(call) / id(dependant) — the
object's memory address. Python recycles id() after an object is garbage
collected, so a short-lived callable could be collected and a later object
allocated at the same address, then wrongly served the dead object's cached
entry. DepsCache holds a strong reference to every keyed object (via
keep_alive) so its address stays reserved for the cache's lifetime.
Calling loop-safe dependencies inline¶
FastAPI awaits fastapi.dependencies.utils.run_in_threadpool(call, **values) for
every sub-dependency that is neither a coroutine nor a generator — the only call
site of that module global, from FastAPI 0.112.4 to 0.143.1.
patch_fastapi_run_in_threadpool() replaces the global: a callable that is
loop-safe (or any class, with inline_classes=True) is called inline, everything
else is delegated to the function the global held when patching.
- Why the global, not
Dependant.call— rewritingcallinto anasyncfactory would change the key FastAPI looks overrides up with and stores values under: an override registered on the original class would no longer be found, and shared sub-dependencies would be built twice once overrides are set. Patching the global leaves thecall, the cache key and the override lookup untouched. - Overrides — the
callthe replacement receives is the effective one, afterdependency_overrides: an override is judged on its own marker. - Not affected — sync generator dependencies go through
contextmanager_in_threadpooland sync endpoints throughfastapi.routing, so both keep their threadpool hop. - Guard — a test fails if FastAPI stops awaiting sync dependencies through the module global.
Skipping cached sub-trees at request time¶
solve_dependencies loops over a dependant's sub-dependencies, recurses into each
one, and only then checks whether the sub-dependency's value is already in the
request's dependency_cache. patch_fastapi_solve_dependencies() wraps it: when
the caller's sub-dependency is cached, the recursive call returns an empty
SolvedDependency straight away. The caller then hits its own cache check and
reuses the value, so no FastAPI code is copied.
- Patch points —
fastapi.dependencies.utils.solve_dependencies(the recursion looks this module global up at every call) andfastapi.routing.solve_dependencies(imported by name; HTTP routes, WebSocket routes and route groups), which it shares with the resolution plan (see below). The root call never receives a cache, so it is never skipped. - Cache key — it must be the exact key FastAPI stores the value under: a
dataclass field before FastAPI 0.121,
Dependant.cache_keyas acached_propertyup to 0.139, andfastapi.dependencies.models._get_cache_keyfrom 0.140, called with the_uses_scopes_cachememo the recursion threads through. - The caller's sub-dependency — when
dependency_overridesis not empty, FastAPI rebuilds every sub-dependant, overridden or not, before recursing. The rebuilt dependant always hasuse_cache=Trueand drops its ownSecurityscopes, so its key may not be the one the caller checks. The wrapper therefore tests the caller's own sub-dependant: before delegating, it publishes the dependant's sub-dependants in aContextVar, and each recursive call takes the next one, since FastAPI recurses exactly once per sub-dependant, in order. A sub-dependant whosenameor (overridden)calldoes not match what the recursive call received is never skipped. TheContextVaris per asyncio task, so concurrent requests never share it. - Guards — tests fail if FastAPI stops resolving the recursion through the
module global, changes the fields of
SolvedDependency, keys its request cache differently, or stops recursing once per sub-dependant in order.
Solving routes from a precompiled plan¶
patch_fastapi_resolution_plan() replaces the recursion itself.
fastapi_cache_di.plan.compile_plan flattens a route's dependency tree into
frames (a dependant whose own parameters are extracted after its
sub-dependencies) and steps (one per occurrence of a sub-dependency), in
FastAPI's evaluation order: depth first, sub-dependencies in the order of
dependant.dependencies. Each step carries, precomputed, its request cache key,
the kind of its callable (coroutine, sync, sync or async generator), its stack
scope, and each frame its non-empty parameter fields, special parameters
(Request, WebSocket, HTTPConnection, Response, BackgroundTasks,
SecurityScopes) and OAuth scopes. At request time, the plan runs the steps in
a single loop.
- Patch point —
fastapi.routing.solve_dependencies, the root call. One dispatcher owns it while either the plan or the sub-tree skip is active: it runs the plan when the plan is active, and the currentfastapi.dependencies.utils.solve_dependencies(the skip wrapper or FastAPI) otherwise. The first patch saves FastAPI's original, the last unpatch restores it, in any order.Dependant.callis never rewritten, so the override lookup and the cache keys stay FastAPI's. - FastAPI helpers — the functions the plan calls (
request_params_to_args,request_body_to_args,run_in_threadpool, the generator helper,solve_dependencies) are looked up onfastapi.dependencies.utilsat call time, as FastAPI does, sopatch_fastapi_run_in_threadpool()still applies. - Repeated occurrences — a repeated occurrence of a
use_cache=Truedependency is a step that reads the request cache. Its value is missing only when its first occurrence failed validation; FastAPI then solves it again and reports its errors once more, so the step hands that sub-tree tofastapi.dependencies.utils.solve_dependencies, which duplicates the errors exactly like FastAPI. - Overrides — the plan is compiled with
dependency_overridesapplied, rebuilding every sub-dependant withget_dependantlike FastAPI, with the scope arguments of each version. The snapshot of the overrides (pairs compared by identity) is checked at every request, immediately when the dict is empty. The rebuilt sub-trees are not kept: frames and steps only keep the values they read, and a repeated occurrence keeps theget_dependantarguments to rebuild its dependant on the error path only. - Storage —
Dependantcannot carry the plan: from FastAPI 0.140 it is a slotted dataclass, without room for an extra attribute nor weak references. The plans are stored on the route'sdependency_overrides_provider(the app), keyed byid()of the root dependant with a strong reference to it (the same protection asid()recycling protection), so they are freed with the app. A root call without a provider is solved by FastAPI. - Versions — differences between FastAPI versions are confined to a few
adapters chosen from the fields of
Dependantand the functions FastAPI defines: the cache key, the OAuth scopes, the callable kind, the exit stacks (per scope from 0.121) and theget_dependantscope arguments. - Guards — an equivalence test compares the plan with FastAPI on a reference tree (values, errors, request cache, call and exit order) on every version of the compatibility matrix, and a benchmark gate requires the plan to be at least twice as fast as the sub-tree skip on a tree of 100 dependencies and 211 edges.