FastAPI's Dependency Caching: One Request, One Call

WHY IT EXISTS To solve the problem of efficiently sharing resources within the context of a single API request. Without a per-request cache, you might repeatedly fetch a user's data from a token or open multiple database connections for one operation, which is inefficient and error-prone.

THE MENTAL MODEL A FastAPI dependency is a singleton scoped to a single request. When a request comes in, FastAPI builds a dependency graph. If it sees the same dependency function needed in multiple places, it runs the function only once, caches the result, and then injects that same result everywhere it's needed for that request.

HOW IT WORKS When you use Depends(my_dependency) in multiple places for a single API endpoint (e.g., in the path operation signature and also inside another sub-dependency), FastAPI does not call my_dependency for each Depends. It calls it once, the first time it's needed, saves the return value in a request-specific cache (a dictionary), and reuses that value for all subsequent needs within that same API call. The key for this cache is the dependency function itself, so Depends(common_dep) always resolves to the same value per request.

WHEN TO USE IT This implicit caching is perfect for any resource you want to create once and share during a single request's lifecycle. Three common places this is essential: first, for creating a single database session to be used by all business logic; second, for fetching the current authenticated user object once and using it for multiple permission checks; third, for fetching configuration that might be needed by several sub-routines.

WHEN NOT TO USE IT Do not rely on this mechanism for caching across different requests or different users. It is not a replacement for a proper application-level caching layer like Redis or Memcached. The dependency cache is ephemeral and tied strictly to the lifecycle of one request. Attempting to use it for cross-request state will fail silently and lead to bugs.

ONE CANONICAL EXAMPLE Imagine a dependency get_current_user that decodes a JWT. Another dependency, check_user_permissions(user: User = Depends(get_current_user)), checks the user's role. Your endpoint might be def get_items(user: User = Depends(get_current_user), permissions_ok: bool = Depends(check_user_permissions)). FastAPI is smart enough to see get_current_user is needed twice. It will call it only once, then pass the resulting User object to both the get_items function and the check_user_permissions dependency.