In FastAPI 0.143, how does the lifespan parameter run startup and shutdown code, and what happens to on_event handlers?
answer
- one function, two halves
- an async context manager
- yield separates startup from shutdown
- on_event is deprecated
basics
~10 sFastAPI(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 sYou 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 linesfrom 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
Recall the shape: an async function with one yield, decorated with @asynccontextmanager, passed as FastAPI(lifespan=...). Before yield is startup, after yield is shutdown.
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.
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.
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.