In FastAPI, why are settings usually injected with Depends(get_settings) where get_settings is wrapped in @lru_cache, and what does each part do?
answer
- two caches, two scopes
- Depends caches per request only
- lru_cache keeps one object
- overrides keyed by the function
basics
~10 sDepends(get_settings) makes settings an injectable dependency that tests can replace through app.dependency_overrides. @lru_cache makes get_settings build Settings once per process, since Depends alone caches only within a single request.
solid answer
~30 sThe dependency and the cache solve different problems. Declaring `settings: Annotated[Settings, Depends(get_settings)]` makes configuration an explicit input that a test can swap with `app.dependency_overrides[get_settings] = ...`, keyed by the same function object. But FastAPI's dependency cache lasts one request, so a bare `get_settings` would call `Settings()` and re-read the environment on every request. `@lru_cache` on the no-argument `get_settings` returns the same object for the life of the process. Consequences worth naming: `use_cache=False` does not force a reload; a changed environment variable is not seen until `get_settings.cache_clear()`; and every request shares one `Settings` object, so it must be treated as read-only.
code
python · 33 linesfrom functools import lru_cache
from typing import Annotated
from fastapi import Depends, FastAPI
from pydantic_settings import BaseSettings
class Settings(BaseSettings):
model_path: str = "/models/classifier.bin"
max_batch: int = 16
@lru_cache
def get_settings() -> Settings:
return Settings() # reads the environment once per process
SettingsDep = Annotated[Settings, Depends(get_settings)]
app = FastAPI()
@app.get("/config")
async def config(settings: SettingsDep) -> dict:
return {"model_path": settings.model_path, "max_batch": settings.max_batch}
def get_test_settings() -> Settings:
return Settings(model_path="/tmp/tiny-model.bin", max_batch=2)
# In a test: replace the dependency, keyed by the decorated get_settings itself.
app.dependency_overrides[get_settings] = get_test_settingsgo deeper
Know the shape: a Settings class, a get_settings function with @lru_cache, and Depends(get_settings) in the endpoint signature.
Separate the two caches: Depends reuses a result within one request, lru_cache reuses it for the process, and the override is keyed by the decorated function.
Name the sharp edges: use_cache=False does not reload, environment changes need cache_clear, a parameter on get_settings becomes a request input, and the shared Settings must be treated as read-only.
Decide how configuration flows through the codebase: injected everywhere through one cached dependency, or read in a few places, and how tests swap it.
## The pattern FastAPI's documented way to hand configuration to endpoints combines three pieces: 1. A Pydantic `BaseSettings` class (from the pydantic-settings package) that reads its fields from environment variables. 2. A function, conventionally `get_settings`, that returns `Settings()` and is decorated with `@lru_cache` from the standard library's `functools`. 3. Endpoints that receive it as a dependency: `settings: Annotated[Settings, Depends(get_settings)]`, often through an alias like `SettingsDep`. Each piece solves a different problem, and interviewers want to hear which one does what. ## Why a dependency instead of a module-level object The simplest alternative is `settings = Settings()` in a `config.py` that every module imports. It works, but the value is fixed at import time and every consumer reaches for the same global. Serving settings **through `Depends`** buys two things: - **Overriding in tests.** `app.dependency_overrides[get_settings] = get_test_settings` replaces the value for every path operation that declares `Depends(get_settings)`, without patching imports or environment variables. The override dict is keyed by the **callable object** passed to `Depends`. - **Explicit inputs.** An endpoint's signature shows that it reads configuration, and the generated schema is unaffected because settings come from no request source. ## Why `@lru_cache` on top `Depends` caches results, but **only within one request**. With `use_cache=True`, the default, a dependency used by several parameters or sub-dependencies of the same request runs once for that request. The next request runs it again. Without `@lru_cache`, `get_settings` would build a new `Settings` object per request, and with it read the environment and any `.env` file again. `@lru_cache` caches across calls for the life of the process. Because `get_settings` takes no arguments, the first call stores the result and every later call returns the **same object**. The FastAPI documentation describes this as behaving almost like a global variable that can still be overridden in tests. | Layer | Scope of reuse | Controlled by | |---|---|---| | `Depends` result cache | one request | `use_cache` (default `True`) | | `@lru_cache` on `get_settings` | the whole process | `get_settings.cache_clear()` | | `app.dependency_overrides` | what `Depends(get_settings)` resolves to | the test that sets it | ## How the parts interact Several consequences follow, and they are the usual follow-up questions: - **`use_cache=False` does not reload settings.** It only turns off the per-request cache; the call still reaches the `lru_cache` wrapper, which returns the stored object. - **Changed environment variables are not seen** until `get_settings.cache_clear()` runs or the process restarts. That is the intended trade: settings are read once, at the first call. - **The object is shared.** Every request receives the same `Settings` instance, so treat it as read-only; Pydantic models allow attribute assignment by default. ## Mistakes reviewers catch - **`@lru_cache` on a function with request-dependent arguments.** The cache is keyed by arguments, so a settings factory that takes, say, a tenant name builds one object per distinct value and keeps up to 128 of them, the default `maxsize`. The documented `get_settings` takes no arguments for that reason. - **Building `Settings()` inside the endpoint body.** It skips both the cache and the override, and re-reads the environment on every call. - **Mutating the shared object in a request**, for example toggling a flag on `settings`. Every later request in that process sees the change, and tests start to depend on their order. - **Forgetting the cache in tests that patch the environment.** Without `get_settings.cache_clear()`, the first test to call `get_settings` fixes the value for the rest of the run. ## Writing it ```python @lru_cache def get_settings() -> Settings: return Settings() SettingsDep = Annotated[Settings, Depends(get_settings)] @app.get("/config") async def config(settings: SettingsDep) -> dict: return {"model_path": settings.model_path} ``` How the `Settings` class finds its values (environment variables, `.env` files, secrets directories, and which wins) is pydantic-settings' business and is covered with the Pydantic settings material. The FastAPI-specific part is the wiring above: one cached factory, injected through `Depends`, replaced through `app.dependency_overrides`.
- In FastAPI, does Depends(get_settings, use_cache=False) make each request read fresh settings?No. `use_cache=False` only stops FastAPI reusing the result within one request. Each resolution still calls the `lru_cache` wrapper, which returns the object stored at the first call. To read new values you call `get_settings.cache_clear()` or restart the process.
- In FastAPI, why does a cached get_settings dependency take no parameters?Two reasons. `lru_cache` keeps one result per distinct argument tuple, so with no arguments there is exactly one `Settings` for the process. And FastAPI treats a dependency's parameters as request inputs: `get_settings(env: str)` would turn `env` into a required query parameter and cache one `Settings` per value a client sends.
- Depends already caches results across requests, so lru_cache adds nothing.
- Depends(get_settings, use_cache=False) forces settings to be re-read each request.
- Giving get_settings a parameter still leaves exactly one cached Settings.
- A changed environment variable is picked up on the next request automatically.
- Changing a field on the injected Settings affects only the current request.