FastAPI Lifespan Event

What It Is?

It lets you run code once at startup (before requests are served) and once at shutdown (after the server stops accepting requests). It’s the modern replacement for the deprecated @app.on_event(“startup”/”shutdown”) decorators.

Typical uses: opening/closing a DB connection pool, loading an ML model, connecting to Redis, starting a background scheduler etc.

Basic Syntax

from contextlib import asynccontextmanager
from fastapi import FastAPI

@asynccontextmanager
async def lifespan(app: FastAPI):
    # --- STARTUP ---
    print("Starting up...")
    # startup code

    yield

    # --- SHUTDOWN ---
    print("Shutting down...")
    # shutdown code

app = FastAPI(lifespan=lifespan)

• Code before yield runs on startup.
• Code after yield runs on shutdown.
• yield is where your app actually runs and serves requests.

Real Example

@asynccontextmanager
async def lifespan(app: FastAPI):
    db = await connect_db()
    cache = await connect_cache()

    try:
        yield
    finally:
        await db.close()
        await cache.close()

Handling Startup Errors

• If an exception is raised before yield, the app fails to start (server won’t come up) — good for “fail fast” on missing config or unreachable DB.
• If an exception is raised after yield (during shutdown), it’s logged but doesn’t prevent shutdown from completing.
• Wrap risky shutdown steps in try/finally if you have multiple resources to release, so one failure doesn’t skip cleanup of the others:

Sharing Resources with Routes

Use app.state to attach objects created at startup so routes can access them.

from contextlib import asynccontextmanager
from fastapi import FastAPI, Request
import httpx

@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.http_client = httpx.AsyncClient()
    yield
    await app.state.http_client.aclose()

app = FastAPI(lifespan=lifespan)

@app.get("/ping")
async def ping(request: Request):
    client = request.app.state.http_client
    resp = await client.get("https://example.com")
    return {"status": resp.status_code}

Key Rules & Gotchas

The Old Way @app.on_event() and Its Problems

Before lifespan, startup/shutdown logic used two separate decorators:

from fastapi import FastAPI

app = FastAPI()

@app.on_event("startup")
async def startup():
    app.state.db = await connect_db()

@app.on_event("shutdown")
async def shutdown():
    await app.state.db.close()

This worked, but had real technical limitations in production apps:

• No shared scope between startup and shutdown: Startup and shutdown are two independent functions. Any resource created in startup() has to be stashed somewhere external (usually app.state or a global) for shutdown() to reach it – there’s no natural local variable shared between the two.

• No structured error handling: You can’t wrap both halves in one try/finally. If shutdown needs to guarantee cleanup even when something in startup partially failed, you have to build that safety net yourself.

• Fragmented, hard-to-follow logic: Related setup/teardown for the same resource (e.g. open a DB pool → close it) lives in two different functions, often far apart in the file, instead of one readable block.

• Multiple handlers, unclear ordering: You can register several @app.on_event(“startup”) functions. FastAPI runs them, but reasoning about ordering and dependencies between them (e.g. “cache must start after DB”) gets messy fast.

• Doesn’t compose well There’s no clean way to combine reusable startup/shutdown units from different modules (e.g. one for DB, one for cache) into a single coherent lifecycle — you end up with a growing pile of loosely related event handlers.

• Deprecated FastAPI (since 0.95.0) marks on_event as deprecated. It still works today but is not the recommended or actively evolving API, and may be removed in a future major version.