Inject request dependencies
A route needs authenticated user information, configuration, or a database session supplied by application code.
FastAPI · Function
Depends
Depends declares a callable that FastAPI resolves and injects into a route or another dependency. It also controls per-request result caching and, for yield dependencies, cleanup timing.
- Since
- 0.121.0 for Depends(scope="function") support
How it works
Depends declares a callable that FastAPI resolves during request handling. FastAPI inspects that callable's parameters, invokes it with any required values, and injects its result into the dependent route or dependency; caching is enabled by default within one request.
Syntax
Depends(dependency=None, *, use_cache=True, scope=None)Parameters
| Name | Type | Description |
|---|---|---|
dependency | Callable[..., Any] | None | A callable dependency. Pass the object itself; FastAPI invokes it and resolves its parameters. |
use_cache | bool | Whether to reuse the dependency result after its first call within the same request. |
scope | Literal["function", "request"] | None | For yield dependencies, controls when cleanup after yield runs. Supported values are "function" and "request". |
Returns
Returns a Depends object used by FastAPI to declare dependency injection; the dependency's resolved value is injected into the dependent parameter.
Key points
- Use Depends to declare a callable that FastAPI should resolve as a dependency.
- The public import is from fastapi import Depends.
- Its signature accepts an optional callable, request-level caching control, and an optional lifecycle scope.
- The dependency's return value becomes available to the parameter that declares it.
Common mistakes
- Pass the callable itself, such as get_user_id, rather than invoking it as get_user_id().
- The default cache reuses a dependency result during the request; disable it when repeated declarations must execute again.
- For yield dependencies with scope="request", cleanup runs after the response is sent; scope="function" ends cleanup before sending it.
Example: Inject a dependency into a route
from typing import Annotated
from fastapi import Depends, FastAPI
app = FastAPI()
def get_user_id() -> int:
return 42
@app.get("/me")
def read_me(user_id: Annotated[int, Depends(get_user_id)]):
return {"user_id": user_id}FastAPI calls the dependency for each request and supplies its returned value to the route parameter.
When to use it
Reuse resolved values
Several dependencies share the same sub-dependency during one request.
Control resource lifetime
A resource dependency uses yield and needs cleanup at a defined point in response handling.
Run side-effect dependencies
A dependency needs to be executed for validation or authorization, but its return value is not needed by the route.
Interview questions
QWhat does Depends do?
Depends accepts a dependable callable and tells FastAPI to resolve it rather than treating it as an ordinary parameter. FastAPI calls the dependency with its declared parameters and assigns the returned value to the route parameter.
Follow-up: What can be passed besides a function? Any callable can be used, including a class or an instance implementing __call__; FastAPI analyzes that callable's parameters.
QHow does dependency caching work?
use_cache defaults to True. If the same dependency is needed more than once in a request, FastAPI reuses the value from its first call.
Follow-up: When would you set it to False? Set use_cache=False when the dependency must run again for another declaration in the same request.
QWhat is the purpose of the scope parameter?
scope controls the lifetime of dependencies that use yield. With function scope, cleanup after yield runs when the path operation finishes but before the response is sent; request scope runs cleanup after the response is sent.
Follow-up: Which scope is the default? request is the default scope, and it starts before the path operation similarly to function scope.
Related
SecurityAnnotatedFastAPIAPIRouterdependency_overrides