{"componentChunkName":"component---src-templates-blog-post-js","path":"/blog/2026-08-06-fastapi-dependency-injection-explained/","result":{"data":{"site":{"siteMetadata":{"title":"M.Hassan Ahmed","author":"Hassan11196"}},"markdownRemark":{"id":"9799f54d-383c-5c54-91d3-7fd06672e250","excerpt":"Every endpoint in a real backend needs the same handful of things before it can do any work: a database session, the authenticated user, a settings object…","html":"

Every endpoint in a real backend needs the same handful of things before it can do any work: a database session, the authenticated user, a settings object, maybe a rate limiter. You can build those inline at the top of each handler. It works, and it rots. The construction code gets copy-pasted, the teardown gets forgotten, and the day you want to run the handler in a test, you find there is no seam to swap the real database for a fake one.

\n

FastAPI’s answer is Depends: you declare what a handler needs as a parameter, and the framework builds it before the handler runs. This post is for engineers who already use Depends and want to know what it does underneath. It covers how a dependency graph gets resolved, why a shared dependency runs only once, what yield actually guarantees about cleanup, and the places it leaks.

\n

The examples follow the shape of the Archi backend I worked on for CMS computing operations at CERN. There, every request has to be authenticated against CERN SSO (single sign-on) and handed a scoped database session before it touches a thing.

\n

Depends is a resolver, not a container

\n

If your mental model of dependency injection comes from Spring or .NET, drop the part about a global registry. There is no container you register services into, and no separate file that configures lifetimes. A dependency in FastAPI is just a callable. Depends(get_db) on a parameter means one thing: before you call this function, call get_db, and pass what it returns as this argument.

\n

In this example, the endpoint needs a user, and getting the user needs a token and settings:

\n
from fastapi import Depends, FastAPI\n\napp = FastAPI()\n\ndef get_settings() -> Settings:\n    return Settings()  # env-driven config\n\nasync def get_current_user(\n    token: str = Depends(get_token),\n    settings: Settings = Depends(get_settings),\n) -> User:\n    return await verify(token, settings.jwt_key)\n\n@app.post(\"/documents\")\nasync def create_document(user: User = Depends(get_current_user)):\n    return {\"owner\": user.id}
\n

The wiring is the function signature. get_current_user needs a token and settings, so it declares them as Depends parameters, and FastAPI resolves those first. That nesting is the whole idea: dependencies can depend on other dependencies, and the result is a graph that FastAPI walks for you. There is no registration step and no lifetime annotation. Whatever a function needs, it asks for in its parameters.

\n

One request, one pass through the graph

\n

When a request arrives, FastAPI resolves the graph from the endpoint down. create_document needs a user; the user needs a token and settings; the token might need the raw request. FastAPI walks that tree and calls each node.

\n

The part worth internalizing is caching. Within a single request, FastAPI calls each dependency once and reuses the result for every other dependency that asks for it. If get_current_user and get_db both depend on get_settings, get_settings runs a single time and both receive the same object. This is on by default; the cache key is the callable plus its arguments.

\n

\"A

\n

The trap is assuming this cache spans requests. It does not. A dependency that runs “once” runs once per request, and the next request starts clean. So get_settings above builds a fresh Settings() on every single request, which is wasteful if reading config is expensive. If you want a genuine app-wide singleton, memoize it yourself:

\n
from functools import lru_cache\n\n@lru_cache\ndef get_settings() -> Settings:\n    return Settings()
\n

Now get_settings still appears as a normal dependency and can still be overridden in tests, but the object is built once for the life of the process. The lru_cache handles the app-scoped part; Depends handles the request-scoped wiring. Keeping those two responsibilities separate is most of what “getting DI right” means here.

\n

yield dependencies: setup, hand off, tear down

\n

A plain return dependency produces a value. A yield dependency produces a value and a cleanup step, which is exactly what a database session or any other acquired resource needs:

\n
async def get_db():\n    session = SessionLocal()\n    try:\n        yield session\n    finally:\n        await session.close()
\n

The function has three parts:

\n\n

The timing of that teardown is the detail people get wrong. The exit code runs after the response has been sent to the client, not before. Your handler returns, the bytes go out, and only then does session.close() fire.

\n

\"A

\n

With more than one yield dependency, FastAPI unwinds them in reverse order of setup, the way a stack of context managers would: the last one opened is the first one closed. That ordering is a guarantee, not luck. A dependency that opened a transaction inside a dependency that opened a connection tears down in the safe order.

\n

Two sharp edges come straight out of this timing. Both are documented behavior rather than bugs:

\n\n

Auth is the dependency that earns its keep

\n

The single best use of Depends is authentication, because it turns “is this caller allowed?” into one declared input that every protected route shares. In CloudCanvasAI, a Claude-powered document platform I built, the server verifies a Firebase ID token on every request. That verification is a dependency, not a line repeated in forty handlers:

\n
async def require_user(token: str = Depends(get_token)) -> User:\n    user = await verify_firebase_token(token)\n    if user is None:\n        raise HTTPException(status_code=401, detail=\"invalid token\")\n    return user
\n

When a handler wants the user object, it takes user: User = Depends(require_user). When a route only needs the check and not the return value, attach the dependency at the router so it covers a whole group of routes at once:

\n
router = APIRouter(dependencies=[Depends(require_user)])
\n

For anything parameterized, like role checks, reach for a class with __call__. The instance holds the config (here, the required role), and the call does the work, so you get a reusable, testable guard:

\n
class RequireRole:\n    def __init__(self, role: str):\n        self.role = role\n\n    def __call__(self, user: User = Depends(require_user)) -> User:\n        if self.role not in user.roles:\n            raise HTTPException(status_code=403, detail=\"forbidden\")\n        return user\n\nadmin_only = RequireRole(\"admin\")
\n

Testing is the reason this pays off

\n

Here is the seam that inline construction never gives you. FastAPI lets you override any dependency at test time without touching a single handler:

\n
from myapp import app, get_db\n\ndef override_get_db():\n    yield test_session\n\napp.dependency_overrides[get_db] = override_get_db
\n

Every route that depends on get_db, directly or three levels deep, now receives the test session instead of the real one. There is no monkeypatching of module globals and no conditional branch for a test mode. The override map is keyed by the original callable, so the same trick swaps out require_user for a fixture that returns a canned user, or get_settings for a config that points at a throwaway database.

\n

This is why declaring dependencies beats constructing them inline. The declaration gives you a named place to reach in and substitute; inline construction gives you nothing to grab.

\n

Where it breaks

\n

Sync dependencies and the event loop. A dependency written as def, not async def, runs in an external threadpool, exactly like a sync path operation, which keeps it from blocking the loop. But the threadpool is finite, so a sync dependency doing slow blocking I/O on a hot path will consume workers and starve everything else, the same failure I wrote about for blocking the FastAPI event loop. If a dependency does real I/O, make it async and use an async client; if it must stay sync, keep it cheap.

\n

Treating request scope as app scope. The most common performance bug I see is a dependency that constructs an expensive client (an HTTP session, a model handle, a connection) on every request, because it lives in a plain Depends. Per-request is the default, and per-request construction of a shared resource is pure overhead. App-lifetime objects belong in the lifespan handler and get read out of application state, not rebuilt per call.

\n

Silent cache surprises. Per-request caching is usually what you want, but if a dependency has side effects and you expected it to run twice in one request, it will run only once. Set Depends(dep, use_cache=False) when you genuinely need a fresh call each time. This is rare, and reaching for it is often a sign the logic wants to be plain code inside the handler instead.

\n

Over-broad dependencies. A Depends that quietly does three unrelated things (verifies auth, opens a transaction, and logs) is hard to override in a test, because you cannot replace one part without replacing all three. Keep each dependency to one job. Small dependencies compose; fat ones fight you.

\n

Tradeoffs, and what I would keep in mind

\n

FastAPI’s dependency system is a request-scoped resolver with per-request caching and stack-ordered cleanup. That is a smaller thing than a full inversion-of-control container (the kind of framework that creates and wires every object for you), and the mistake is trying to grow it into one. It has no notion of scoped, transient, and singleton lifetimes. There is request scope, and there is whatever you memoize yourself for the process.

\n

Once you stop expecting the missing features, the model is clean:

\n\n

For the backends I build, that is enough, and I would not reach for more. Archi authenticates every operator request and hands it a scoped session through exactly this mechanism; CloudCanvasAI verifies a token on every call the same way. The plumbing stays boring and out of the handlers, which is the point: let the framework build what each request needs, so the endpoint is left to do the one thing it exists to do.

\n
\n

Diagrams by M. Hassan Ahmed, created for this post and released under CC0 (public domain). No external image was used.

","frontmatter":{"title":"How FastAPI Dependency Injection Actually Works","date":"2026-08-06T00:00:00.000Z","description":"A practical guide to FastAPI dependency injection: how Depends resolves a graph, yield setup and teardown, per-request caching, and where it leaks.","thumbnail":{"childImageSharp":{"fluid":{"base64":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAALCAIAAADwazoUAAAACXBIWXMAAAsSAAALEgHS3X78AAAB30lEQVQozy2Q6Y6bMBSF+TFqAtgGbLAxO4Q1kJUsk0VKmnamo7bTef+36SWJ9Onq2NfnLlas8EDDI/F3UftWrv9W/b9m+1WtP9PZRzr7Vaz+TBa/s/kHUPWfXvnd8PdgeaDohq8ZPqZRUq6bxbFdnheby3RxLtt91e2b+XG6PEGsutfF5ppVPTIDeK/fUXQr0mmEWYxorJmRChiQDkA/sZ6oRoRogmkyWAZixeC56ZZU1pZbAoQliKaI5boZ3Am1+2gq8YAxlo8jVIeU4pW3sv8S+c2MzqJ4N4Mt5h0WHXaqYTwzNEUJMFk7/tT2GmxnxJkAUFohvLHkDPMpchrCW51mKpEqFohlyC4NXrnZTk62k+5Sr37ks4tINna4tLxOt0JFRa6KhEZcADyDMDwANBRi2dXNXuPmWCzfJ/OffnEIigNPelNO751ZTGz4gxDT0HBSiCqW8GfD2iwnooY+PFnJbCvSnvozuDHd1pQNLKXY8SGob155ddITi09EdIi3yIHCsYq4bniwJ5WVJXJb1lSWVBS2V1s814insLAPq0tUX5x4bwY75NQqHuYHJwiNSOaCraBiwmTBZG7xDATMC2+Ubxp7GVsvYwpipA+MEb8jHmKk87F+F8gZoad4pP4DMNpGYwqfMVAAAAAASUVORK5CYII=","aspectRatio":1.899441340782123,"src":"/static/df58b502e7deb0a3d25d6eacd0c715a6/40a76/hero.png","srcSet":"/static/df58b502e7deb0a3d25d6eacd0c715a6/c972b/hero.png 340w,\n/static/df58b502e7deb0a3d25d6eacd0c715a6/27625/hero.png 680w,\n/static/df58b502e7deb0a3d25d6eacd0c715a6/40a76/hero.png 1360w,\n/static/df58b502e7deb0a3d25d6eacd0c715a6/ed396/hero.png 2000w","sizes":"(max-width: 1360px) 100vw, 1360px"}}}}}},"pageContext":{"slug":"/2026-08-06-fastapi-dependency-injection-explained/","previous":"blog/2026-08-07-argocd-applicationsets-many-clusters/","next":"blog/2026-08-10-async-connection-pooling-fastapi/"}},"staticQueryHashes":["32046230"]}