In FastAPI, how does a dependency written with yield instead of return run setup and cleanup around a request?
answer
- before, during, after
- the yielded value is injected
- try / finally around the yield
- cleanup in reverse order
- default timing: after the response
basics
~20 sFastAPI runs the code before the yield ahead of the endpoint, injects the yielded value, and runs the code after it once the request finishes, by default after the response is sent. Wrap the yield in try/finally.
solid answer
~40 sFastAPI turns a dependency that uses `yield` instead of `return` into a context manager. Everything up to the `yield` runs before the path operation, the yielded value is what the parameter receives, and everything after the `yield` is exit code. In FastAPI 0.143 a yield dependency defaults to `scope="request"`, so after a normal return its exit code runs once the response has been sent. If the endpoint raises, FastAPI throws that exception into the generator at the `yield`, so code that must always run belongs in `finally`. With several yield dependencies, exit code runs in reverse order of setup, so a dependency's cleanup can still use its sub-dependencies. Use exactly one `yield`, written as a plain `def` or `async def` generator; FastAPI does the wrapping itself.
code
python · 25 linesimport tempfile
from pathlib import Path
from typing import Annotated
from fastapi import Depends, FastAPI, HTTPException
app = FastAPI()
def get_workdir():
tmp = tempfile.TemporaryDirectory(prefix="render-")
print("setup:", tmp.name)
try:
yield Path(tmp.name) # this value is what the endpoint receives
finally:
tmp.cleanup() # runs whether the endpoint returned or raised
print("teardown: removed", tmp.name)
@app.post("/renders/{name}")
def create_render(name: str, workdir: Annotated[Path, Depends(get_workdir)]):
if name == "bad":
raise HTTPException(status_code=400, detail="Unsupported template")
(workdir / f"{name}.txt").write_text("rendered")
return {"files": sorted(p.name for p in workdir.iterdir())}go deeper
Recall the three parts: code before the yield, the yielded value injected into the endpoint, and exit code after it. Say that cleanup belongs in a finally block.
Explain that the endpoint's exception is thrown in at the yield, that nested dependencies close in reverse order, and that the default request scope runs cleanup after the response.
Show you know where cleanup timing bites: an error response is sent only after cleanup, a successful one before it, and anything the yielded object is handed to must not outlive the request.
Treat yield dependencies as the team's standard for every per-request resource, and set a convention that cleanup lives in finally so reviews can spot a leak at a glance.
## What a yield dependency is A **dependency** in FastAPI is a callable that you hand to `fastapi.Depends`; FastAPI calls it for each request and passes its result to the **path operation function** (the endpoint). A normal dependency uses `return`. A **yield dependency** uses `yield` instead, and that single change gives it a second half: code that runs *after* the endpoint is done. Internally FastAPI wraps an `async def` generator with `contextlib.asynccontextmanager` and a plain `def` generator with `contextlib.contextmanager` (run through its thread pool), then enters the result on an exit stack it keeps for the request. You never write those decorators yourself. | | `return` dependency | `yield` dependency | |---|---|---| | Value injected | the returned value | the yielded value | | Code after the value | none | **exit code**, run later | | Sees the endpoint's exception | no | yes, thrown in at the `yield` | | Typical use | parsing, lookups | anything opened that must be closed | ## The lifecycle, step by step For a request to an endpoint that depends on `get_workdir`, which creates a temporary directory: 1. FastAPI calls `get_workdir()` and runs it up to the `yield`; the directory is created. 2. The yielded `Path` becomes the endpoint's `workdir` argument. 3. The endpoint runs and returns, or raises. 4. On a normal return, FastAPI builds and sends the response; with the default `scope="request"` the exit code runs **after** the response has gone out, including after any background tasks attached to it. 5. If the endpoint raised, FastAPI throws the exception into the generator at the `yield` first, and only then do its exception handlers build the error response. The default timing is one of the things that changed between releases, which is why this answer assumes FastAPI 0.143. `Depends(scope="function")` moves the exit code to just after the endpoint returns, before the response is sent. ## What goes on each side of the yield The split maps naturally onto resources that are acquired and released: | Before the `yield` | After the `yield` | |---|---| | create a temporary working directory | delete it with its contents | | open an outbound client or connection | close it and release its pool | | acquire a lock or a quota slot | release it | | record a start time | record the duration | The yielded object can be anything: the directory's `Path`, the client, or a small object bundling both. Other dependencies may declare it as a sub-dependency and receive the same value. ## Writing cleanup that always runs Because an exception from the endpoint arrives *at the `yield` line*, a bare statement after the `yield` is skipped whenever the endpoint fails. That is why the documented shape is: - `try:` around the `yield`, so the exception can be seen; - `finally:` for the steps that must happen on both paths, such as removing the temporary directory or closing an outbound client; - an `except` only when you have something to do with that specific error, and then a bare `raise` so FastAPI still sees it. Setup that fails before the `yield` behaves differently: the endpoint never runs, and the dependency's own exit code is not reached (a `finally` runs only if the failing line was already inside the `try`). ## Several yield dependencies: reverse order Dependencies form a tree, and any of them may yield. FastAPI enters them in the order it resolves them, sub-dependencies first, and closes them in **reverse** (last in, first out). If `get_c` depends on `get_b`, which depends on `get_a`, the exit code runs `get_c`, then `get_b`, then `get_a`. The reason is practical: a dependency's cleanup may still need the value it received, so that value must still be open when the cleanup runs. ## Rules that trip people up - **One `yield` per dependency.** A second `yield` makes the underlying context manager fail with `RuntimeError: generator didn't stop`. - **Do not decorate it with `@contextlib.contextmanager`.** FastAPI looks through the decorator, sees a generator function, wraps it again, and the request fails with a server error. - **`def` or `async def` both work.** A `def` generator runs its setup and exit code in worker threads; an `async def` one runs on the event loop. - **The yielded object must not outlive the request.** Anything that keeps using it after the exit code has run, such as work handed off to a background task, should open its own resource instead. The database session recipe built on this mechanism, with its commit and rollback, is covered in the material on a session per request.
- If the endpoint raises, does a yield dependency's cleanup run before or after the error response is sent?Before. The exception unwinds through the exit stack first, so FastAPI throws it into each yield dependency at its `yield` and runs their `finally` blocks, and only then do the exception handlers build and send the error response. That holds even for the default `scope="request"`, whose cleanup otherwise waits until after a successful response.
- What happens when a yield dependency raises before reaching its yield?The endpoint never runs and the exception goes to FastAPI's exception handling, so an `HTTPException` raised there becomes the error response. That dependency's code after the `yield` never runs; its `finally` runs only if the failing line was inside the `try`. Yield dependencies that already finished setup are still closed, in reverse order.
- Why does FastAPI close nested yield dependencies in reverse order?Because a dependency's exit code may still use what it received. If a cleanup step writes a final record through a client provided by a sub-dependency, that client must still be open, so FastAPI closes the outer dependency first and the sub-dependency after it, last in, first out.
A tool-hire counter: staff prepare the kit before handing it over, you use it for the job, and they check it back in and clean it only after you have left, whatever state it comes back in.
- A plain statement after the yield runs even when the endpoint raises.
- You should decorate a yield dependency with @contextlib.contextmanager first.
- By default the code after the yield always runs before the response is sent.
- Nested yield dependencies are closed in the same order they were set up.
- Only async def generators can be used as yield dependencies.
Assumes FastAPI 0.143; from 0.106 to 0.117 the exit code ran before the response was sent, 0.118 moved it back after the response, and 0.121 added scope to choose.