skip to content

Lifespan, State & Settings

The lifespan context manager creates shared resources at startup and hands them to requests, and settings arrive through a cached dependency. Interviewers ask where to load a model once.

on this pageshow

explore

questions

5

In FastAPI 0.143, how does the lifespan parameter run startup and shutdown code, and what happens to on_event handlers?

level: juniorimportance: must knowfreq 40%

answer

  1. one function, two halves
  2. an async context manager
  3. yield separates startup from shutdown
  4. on_event is deprecated

basics

~10 s

FastAPI(lifespan=...) takes an @asynccontextmanager function: code before yield runs once before requests are accepted, code after yield runs once at shutdown. App-level on_event handlers are deprecated and stop running once lifespan is set.

solid answer

~40 s

You write an `async def lifespan(app)` with one `yield`, decorate it with `@asynccontextmanager` and pass it as `FastAPI(lifespan=lifespan)`. The ASGI server drives it through the lifespan protocol: the code before `yield` runs once, and only after it finishes does the server accept requests; the code after `yield` runs once when the server shuts down. That makes it the place to load a model or open a client pool, and because both halves live in one function they share local variables. If the startup half raises, Uvicorn logs `Application startup failed. Exiting.` and never serves. `@app.on_event("startup")` and `on_startup=` are deprecated in 0.143, and once you pass `lifespan`, handlers registered on the app that way are no longer called.

code

python · 25 lines
python
from contextlib import asynccontextmanager

from fastapi import FastAPI


def load_model(path: str) -> dict:
    # Stands in for an expensive read of model weights from disk.
    return {"path": path, "weights": [0.1, 0.2]}


@asynccontextmanager
async def lifespan(app: FastAPI):
    model = load_model("/models/classifier.bin")  # startup: once, before any request
    print("model loaded")
    yield {"model": model}
    model.clear()  # shutdown: once, after the last request
    print("model released")


app = FastAPI(lifespan=lifespan)


@app.get("/health")
async def health() -> dict:
    return {"status": "ok"}

go deeper

for a junior

Recall the shape: an async function with one yield, decorated with @asynccontextmanager, passed as FastAPI(lifespan=...). Before yield is startup, after yield is shutdown.

for a middle

Explain the lifespan protocol: the server waits for startup to complete before accepting requests, and why app-level on_event handlers stop running once lifespan is set.

for a senior

Show you have operated it: a failure before yield should stop the process, each worker runs its own lifespan, and cleanup after yield must survive being reached on shutdown.

for a principal

Treat startup cost as a fleet concern: what the lifespan loads per process sets memory per worker and boot time per replica, which constrains how a team scales the service.

## What the lifespan is A FastAPI application often needs **shared resources**: objects that are expensive to create, used by many requests, and in need of cleanup. A machine learning model read from disk, a pooled HTTP client or a database connection pool are the usual examples. Creating them per request is far too slow, and creating them at module import time makes every test that imports the module pay for them. FastAPI's answer is the `lifespan` parameter of the `FastAPI` constructor. It takes an **async context manager factory**: a function that receives the app and returns something usable in `async with`. The usual way to write one is an `async def` function containing a single `yield`, decorated with `@asynccontextmanager` from the standard library's `contextlib`. ```python @asynccontextmanager async def lifespan(app: FastAPI): model = load_model("/models/classifier.bin") # startup yield {"model": model} # the app serves requests here model.clear() # shutdown app = FastAPI(lifespan=lifespan) ``` ## When each half runs The ASGI server drives the lifespan through the ASGI **lifespan protocol**, a separate message channel from HTTP requests: 1. The server starts and sends a `lifespan.startup` message. 2. FastAPI enters the context manager, so the code **before `yield`** runs once. 3. When `yield` is reached, FastAPI reports `lifespan.startup.complete` and the server begins accepting requests. 4. Requests are served for as long as the process lives. 5. On shutdown the server sends `lifespan.shutdown`; FastAPI resumes the function and the code **after `yield`** runs once. Key consequences: - Code before `yield` runs **once per process**, not once per request. Under `fastapi run --workers 4` each worker process runs its own lifespan, so each loads its own copy of the model. - Code after `yield` is **not** per-request teardown. That is what a dependency with `yield` gives you, and the two are easy to confuse because they look alike. - Starlette documents that the lifespan teardown runs once connections are closed and in-process background tasks have completed. - A value yielded as a dict becomes **lifespan state**, which each request can read through `request.state`. Yielding nothing is also valid. ## When startup fails If the code before `yield` raises, the context manager never yields. Starlette sends `lifespan.startup.failed` with the traceback and re-raises. Uvicorn then logs `Application startup failed. Exiting.` and stops instead of serving requests. That is usually what you want: a service that cannot load its model should fail loudly at boot rather than answer every request with an error. In tests, `fastapi.testclient.TestClient` used as a `with` block raises the same exception when the block is entered. ## The deprecated `on_event` handlers Older material registers startup and shutdown code with `@app.on_event("startup")` and `@app.on_event("shutdown")`, or with the `on_startup=` and `on_shutdown=` constructor lists. In FastAPI 0.143 these still work but are **deprecated**: calling `app.on_event` emits a `DeprecationWarning` that points to lifespan. | | `lifespan=` | `on_event` / `on_startup` | |---|---|---| | Status in 0.143 | recommended | deprecated | | Startup and shutdown share variables | yes, one function | only through globals or `app.state` | | Can hand objects to requests | yes, the yielded dict | only by setting `app.state` or globals | | Wraps cleanup in `async with` / `try` | yes | no | The rule that trips people up: **when you pass `lifespan`, the handlers registered on the app with `on_event` or `on_startup` are not called.** FastAPI only runs them through its default lifespan, which your function replaces. The documentation's summary is "all `lifespan` or all events, not both". One exception exists: `include_router` merges an included router's lifespan into the app's, and that merged lifespan still runs `on_event` and `on_startup` handlers registered on the router itself. Move every handler into the lifespan function rather than rely on that. Background that explains the API: Starlette, which FastAPI is built on, removed `on_startup` and `on_shutdown` support, and since 0.128.3 FastAPI keeps those handlers working with its own default lifespan. ## What to say in an interview - Name the parameter, `lifespan`, and the decorator, `@asynccontextmanager`. - Place the two halves: before `yield` once at startup, after `yield` once at shutdown. - Mention that `on_event` is deprecated and is ignored on the app once `lifespan` is set. - Add one production detail: an exception before `yield` stops the server from starting, and each worker process runs its own lifespan.

  • In a FastAPI app with lifespan set, do on_event handlers registered on an included APIRouter still run?
    Yes. `include_router` merges the router's lifespan into the app's, and a router without its own `lifespan` uses a default one that runs its `on_startup` and `on_shutdown` handlers. Only handlers registered on the app itself are skipped. Mixing the two styles makes startup order hard to read, so move router handlers into the lifespan function or give the router its own `lifespan`.
  • How many times does the lifespan run when FastAPI is served with several worker processes?
    Once per process. Each worker is a separate Python process with its own app object, so each runs the startup half, loads its own copy of the model and runs its own shutdown half. Four workers means four model copies in memory, which is why model-serving services often run one worker per container or replica.

A shop's opening and closing routine: stock the shelves once before the doors open, serve customers all day, then cash up once after the last one leaves. Nobody restocks between customers.

  • The code after yield runs after every request, like a dependency's teardown.
  • on_event handlers on the app still run alongside a lifespan function.
  • If the lifespan raises, the app starts anyway and requests just get 500s.
  • Loading the model at module import time is the same as loading it in the lifespan.
  • The lifespan runs once per machine, shared by all worker processes.

Assumes FastAPI 0.143: on_event is deprecated in favour of lifespan, and FastAPI has run on_startup and on_shutdown handlers itself since 0.128.3 because Starlette dropped them.

open as a page

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?

level: middleimportance: should knowfreq 38%

basics

~10 s

Depends(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.

open as a page

In a FastAPI app, how does a dict yielded from the lifespan reach endpoints through request.state, and how does that differ from app.state?

level: middleimportance: should knowfreq 32%

basics

~20 s

The yielded dict is stored as lifespan state, and the server puts a shallow copy of it into each request, where request.state.model reads it. app.state is one object on the application, set by assignment and read through request.app.state.

open as a page

As the lead of a FastAPI inference service, would you create its model, outbound HTTP client and settings at import time, in the lifespan or through an app factory, and why?

level: principalimportance: should knowfreq 30%

basics

~20 s

Heavy or closable resources go in the lifespan: created before yield, handed over as state, closed after it. A create_app(settings) factory lets tests pass their own settings. Import-time globals load for every importer, tests and tools included.

open as a page

A FastAPI app mounts a second FastAPI app with app.mount(), and the mounted app's lifespan never loads its model; why, and how do you fix it?

level: seniorimportance: nice to knowfreq 18%

basics

~20 s

Only the application the server runs receives lifespan events; app.mount() never forwards them, so a mounted app's lifespan does not run. Use an APIRouter with lifespan= and include_router, which merges it, or enter the sub-app's lifespan from the parent's.

open as a page