What is a sub-dependency?

A dependency that itself declares Depends() in its parameters. FastAPI resolves the whole tree before calling your endpoint.

Is a shared dependency called twice in one tree?

No. Results are cached per request, so a dependency used at two levels runs once.

What happens when a deep dependency raises?

The chain stops there and the client gets that error. The dependencies above it and the endpoint never run.

How do I layer permissions?

Build them as a chain, for example get_current_user, then get_active_user, then get_admin_user, each depending on the one before.

Where do query parameters from sub-dependencies appear?

They are gathered upward, so the endpoint's OpenAPI schema lists parameters from every level of the tree.

How deep is too deep?

When you cannot read the endpoint signature and know what runs. Two or three levels is common, beyond that consider flattening.

Sub-dependencies

FastAPIBy Ashish JangraUpdated 15 October 2026

Dependencies that depend on dependencies, and the tree FastAPI resolves before your handler runs.

Overview

The same syntax, one level down

A sub-dependency is a dependency that itself depends on something else. For example, a function that returns the current user might need the token from the header, and a function that checks admin rights might need the current user. Each piece asks for what it needs, and the framework builds the chain.

This lets you assemble behavior from small, reusable parts. Instead of one large function that reads a token, loads a user, and checks permissions, you write three small ones that each do a single job. Each can be tested alone and reused in different combinations.

This article starts with the syntax, which is the same as for any dependency, just applied one level down. Nothing new needs learning there. It then explains how the cache covers the whole tree. If two branches both need the same dependency, it runs once per request, and both receive the same value.

The next section covers failures. When a dependency deep in the chain raises an error, the whole request stops at that point, and nothing after it runs. This is what makes authentication checks reliable, since the handler cannot be reached by accident.

The article ends with a practical use: layering permissions. You will build up from a logged-in user, to an active user, to an admin, with each level adding one rule on top of the last. It is a clean way to express access control.

A useful way to think about it is as a recipe. The final dish needs a prepared ingredient, and that ingredient needs its own preparation. You list each step once, and FastAPI works out the order. This is also where mistakes in design show up quickly. If a chain becomes hard to follow, that is a sign to split it differently, and the article gives guidance on spotting this early. Each section is short and ends with a habit you can apply straight away, so you finish with working knowledge of how chains are built.

A dependency is a function whose params are request params. And Depends is a request param. So a dependency can depend on another:

def token(authorization: str = Header(default="")):
    return authorization.replace("Bearer ", "")

def current_user(tok: str = Depends(token)):
    ...

def admin_only(user: dict = Depends(current_user)):
    ...

There's no new method here. FastAPI walks the tree from the handler's signature down, calls each function in dependency order, and passes the results up.

Worth knowing

A dependency declares its own dependencies with the same syntax. FastAPI resolves the whole tree before calling the handler.

The per-request cache covers the tree, so a shared node reached by several paths is still called once.

A raise anywhere in the tree short-circuits everything below and after it, including the handler.

Layered permission checks are the natural use: each level adds one rule and an endpoint declares the level it needs.

Every parameter declared anywhere in the tree becomes the endpoint's parameter, and appears in the documentation.

Keep the tree shallow. Three levels reads well; five means the signature no longer tells a reader what the endpoint needs.

from fastapi import Depends, FastAPI, Header, HTTPException app = FastAPI() USERS = {"tok-ada": {"name": "ada", "role": "admin"}} def token(authorization: str = Header(default="")): return authorization.replace("Bearer ", "") def current_user(tok: str = Depends(token)): if tok not in USERS: raise HTTPException(401, "Sign in first") return USERS[tok] def admin_only(user: dict = Depends(current_user)): if user["role"] != "admin": raise HTTPException(403, "Admins only") return user @app.delete("/modules/{i}") def remove(i: int, user: dict = Depends(admin_only)): return {"deleted": i, "by": user["name"]} c = TestClient(app) print(c.request("DELETE", "/modules/7", headers={"authorization": "Bearer tok-ada"}).json()) print("no token:", c.request("DELETE", "/modules/7").status_code)

from fastapi import Depends, FastAPI app = FastAPI() calls = [] def base(): calls.append("base") return "B" def left(b: str = Depends(base)): return "L(%s)" % b def right(b: str = Depends(base)): return "R(%s)" % b @app.get("/x") def x(l: str = Depends(left), r: str = Depends(right), b: str = Depends(base)): return {"l": l, "r": r, "b": b, "base_calls": len(calls)} print(TestClient(app).get("/x").json()) print() print("Three paths reach base; it ran once. That is why the cache matters.")

from fastapi import Depends, FastAPI, Header, HTTPException app = FastAPI() ran = [] def token(authorization: str = Header(default="")): ran.append("token") tok = authorization.replace("Bearer ", "") if not tok: raise HTTPException(401, "No token") return tok def profile(tok: str = Depends(token)): ran.append("profile") return {"tok": tok} @app.get("/me") def me(p: dict = Depends(profile)): ran.append("handler") return p c = TestClient(app) r = c.get("/me") print("no token:", r.status_code, "| ran:", ran) ran.clear() r = c.request("GET", "/me", headers={"authorization": "Bearer abc"}) print("token :", r.status_code, "| ran:", ran)

from fastapi import Depends, FastAPI, Header, HTTPException app = FastAPI() USERS = {"a": {"name": "ada", "role": "admin"}, "r": {"name": "rex", "role": "reader"}} def current_user(x_token: str = Header(default="")): if x_token not in USERS: raise HTTPException(401, "Sign in") return USERS[x_token] def verified(user: dict = Depends(current_user)): return user # a real one would check a flag def admin(user: dict = Depends(verified)): if user["role"] != "admin": raise HTTPException(403, "Admins only") return user @app.get("/public") def public(): return {"level": "public"} @app.get("/account") def account(u: dict = Depends(verified)): return {"level": "verified", "you": u["name"]} @app.get("/admin") def admin_page(u: dict = Depends(admin)): return {"level": "admin", "you": u["name"]} c = TestClient(app) for path in ["/public", "/account", "/admin"]: for tok in ["", "r", "a"]: h = {"x-token": tok} if tok else {} print("%-9s tok=%-2s -> %s" % (path, tok or "-", c.request("GET", path, headers=h).status_code))

from fastapi import Depends, FastAPI, Header, Query app = FastAPI() def paging(limit: int = Query(default=10, le=100)): return limit def locale(x_locale: str = Header(default="en")): return x_locale def context(limit: int = Depends(paging), loc: str = Depends(locale), q: str = Query(default="")): return {"limit": limit, "locale": loc, "q": q} @app.get("/search") def search(ctx: dict = Depends(context)): return ctx c = TestClient(app) print(c.request("GET", "/search?q=vectors&limit=5", headers={"x-locale": "fr"}).json()) print() for p in app.openapi()["paths"]["/search"]["get"]["parameters"]: print(" %-9s in %s" % (p["name"], p["in"]))

from fastapi import Depends, FastAPI app = FastAPI() trace = [] def a(): trace.append("a"); return "a" def b(x: str = Depends(a)): trace.append("b"); return x + "b" def c_(x: str = Depends(b)): trace.append("c"); return x + "c" def d(x: str = Depends(c_)): trace.append("d"); return x + "d" def e(x: str = Depends(d)): trace.append("e"); return x + "e" @app.get("/deep") def deep(v: str = Depends(e)): return {"value": v, "order": trace} print(TestClient(app).get("/deep").json()) print() print("It works. But 'deep' declares one parameter and needs five functions,") print("and nothing in its signature says so.")

def bearer_token(authorization: str = Header(default="")) -> str: if not authorization.startswith("Bearer "): raise HTTPException(401, "Missing bearer token") return authorization[7:] def current_user(token: str = Depends(bearer_token)) -> User: user = decode(token) if user is None: raise HTTPException(401, "Invalid token") return user def active_user(user: User = Depends(current_user)) -> User: if user.disabled: raise HTTPException(403, "Account disabled") return user def admin(user: User = Depends(active_user)) -> User: if not user.is_admin: raise HTTPException(403, "Admins only") return user

About the author

Ashish Jangra builds and maintains VizLearn. Every module here is written and the visualisation behind it hand-built, so the numbers in a readout come from the same code that draws the picture. Corrections are genuinely welcome and get priority over everything else — if a page states something wrong, or an animation misrepresents what the algorithm does, get in touch.

Sub-dependencies

Overview

The same syntax, one level down

Worth knowing