Why would a class be a dependency?

A class is callable, so Depends(MyClass) calls its constructor with parameters read from the request. You get an object with attributes.

Do I need to write Depends(MyClass()) or Depends(MyClass)?

Write Depends(MyClass) to have FastAPI construct it per request. Passing an instance only works if the instance defines __call__.

How do I create a configurable dependency?

Make a class with __init__ for configuration and __call__ for the per-request logic, then pass an instance such as Depends(RoleChecker("admin")).

Should I use a function or a class?

Use a function for simple logic, and a class when you want grouped parameters, shared defaults, or configuration.

Are class instances shared between requests?

A class used as Depends(MyClass) gets a new instance per request. An instance you create yourself at import time is shared, so keep it stateless.

Can a class dependency be a Pydantic model?

Yes, but a model is read as a body unless you mark it with Depends or Query. Use Depends to read its fields from the query string.

Class Dependencies

FastAPIBy Ashish JangraUpdated 15 October 2026

Anything callable works, which is how a dependency gets configuration of its own.

Overview

Callables, not functions

A class dependency is a dependency written as a class instead of a function. The idea rests on a Python fact: anything you can call counts as a callable, and classes are callable. When you pass a class to Depends, FastAPI creates an instance for each request and passes its parameters from the request, just as it would for a function.

This matters when a dependency has configuration of its own. A pagination helper might need a default page size. A permission check might need to know which role to require. A class lets you set those options once and reuse the object in many endpoints, with each use configured differently.

This article starts with the idea that callables work, not only functions, and why that opens up more options. It then describes what a class buys you over a plain function, including grouped parameters and attributes you can read in the handler. A section follows on configured instances, where you create an object with settings and give that object to Depends.

Timing is the next topic. You will see when the construction happens, once per request or once per app, and why that affects what you can safely store inside. The article finishes with returning a model, which keeps the result clean and well described in the docs.

If your dependencies keep growing extra arguments, a class is often the neater answer.

You do not need to be an expert in object-oriented design to use this feature. The classes involved are small, usually just an initializer that stores a few values. The benefit is practical: less repeated code, clearer names in your handlers, and settings that live next to the logic that uses them. Along the way you will see how this approach compares with closures and with simple functions, so you can choose the lightest tool that does the job. Not every dependency needs to be a class. Many are better left as plain functions, and the article is clear about where the line falls. Each section is short and ends with a habit you can apply straight away, so you finish with working knowledge and a clear rule for choosing between the two forms.

Depends takes a callable. A function is the obvious one. A class is a callable too. Calling it makes an instance.

class Pagination:
    def __init__(self, limit: int = 10, offset: int = 0):
        self.limit = min(limit, 100)
        self.offset = offset

def list_modules(page: Pagination = Depends(Pagination)):
    ...

FastAPI reads __init__'s signature just as it reads a function's: limit and offset become query params, checked and documented. The handler receives the instance.

Because the annotation and the callable are the same thing, there's a shorthand:

def list_modules(page: Pagination = Depends()):

Worth knowing

Any callable works. A class is a dependency because calling it constructs an instance, and FastAPI reads __init__'s signature for parameters.

Depends() with no argument uses the parameter's annotation as the callable — the shorthand for a class dependency.

Give a class __call__ and its instances become dependencies, which is how one class produces several configured rules.

The instance is built at import, so configuration is not per-request work; only __call__ runs each time.

A dependency can return a Pydantic model, which gives the result validation, constraints and a documented schema.

Prefer a function when there is no configuration and no state. A class without either is ceremony.

from fastapi import Depends, FastAPI app = FastAPI() class Pagination: def __init__(self, limit: int = 10, offset: int = 0): self.limit = min(limit, 100) self.offset = offset def slice(self, rows): return rows[self.offset:self.offset + self.limit] @app.get("/modules") def list_modules(page: Pagination = Depends(Pagination)): rows = ["m%d" % i for i in range(20)] return {"limit": page.limit, "offset": page.offset, "rows": page.slice(rows)} c = TestClient(app) print(c.get("/modules?limit=3").json()) print(c.get("/modules?limit=3&offset=5").json())

from fastapi import Depends, FastAPI app = FastAPI() class Pagination: def __init__(self, limit: int = 10, offset: int = 0): self.limit, self.offset = limit, offset @app.get("/long") def long_form(page: Pagination = Depends(Pagination)): return {"limit": page.limit} @app.get("/short") def short_form(page: Pagination = Depends()): return {"limit": page.limit} c = TestClient(app) print("long :", c.get("/long?limit=4").json()) print("short:", c.get("/short?limit=4").json()) print() print("Same thing. The annotation supplies the callable.")

from fastapi import Depends, FastAPI, Header, HTTPException app = FastAPI() USERS = {"a": "admin", "r": "reader"} class RequireRole: def __init__(self, role: str): self.role = role def __call__(self, x_token: str = Header(default="")): role = USERS.get(x_token) if role is None: raise HTTPException(401, "Sign in") if role != self.role: raise HTTPException(403, "Needs role %r" % self.role) return role require_admin = RequireRole("admin") require_reader = RequireRole("reader") @app.get("/admin") def admin(role: str = Depends(require_admin)): return {"role": role} @app.get("/reading") def reading(role: str = Depends(require_reader)): return {"role": role} c = TestClient(app) for path in ["/admin", "/reading"]: 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))

import json from typing import Literal from fastapi import Depends, FastAPI, Query from pydantic import BaseModel, Field app = FastAPI() class Filters(BaseModel): q: str = Field(default="", max_length=50) limit: int = Field(default=10, ge=1, le=100) sort: Literal["title", "minutes"] = "title" def filters( q: str = Query(default="", max_length=50), limit: int = Query(default=10, ge=1, le=100), sort: Literal["title", "minutes"] = "title", ) -> Filters: return Filters(q=q, limit=limit, sort=sort) @app.get("/modules") def list_modules(f: Filters = Depends(filters)): return f.model_dump() c = TestClient(app) print(c.get("/modules?q=vec&limit=5&sort=minutes").json()) print("bad sort:", c.get("/modules?sort=colour").status_code) print() for p in app.openapi()["paths"]["/modules"]["get"]["parameters"]: print(" %-6s %s" % (p["name"], json.dumps(p["schema"])[:60]))

from fastapi import Depends, FastAPI app = FastAPI() built = [] class RateLimit: def __init__(self, per_minute: int): built.append(per_minute) # runs once, at import self.per_minute = per_minute self.seen = 0 def __call__(self): self.seen += 1 return {"limit": self.per_minute, "calls": self.seen} tight = RateLimit(5) loose = RateLimit(100) @app.get("/tight") def a(r: dict = Depends(tight)): return r @app.get("/loose") def b(r: dict = Depends(loose)): return r c = TestClient(app) print(c.get("/tight").json()); print(c.get("/tight").json()) print(c.get("/loose").json()) print() print("constructed:", built, "- twice, at import, not per request")

from fastapi import Depends, FastAPI app = FastAPI() # No configuration, no state - a function says it more plainly. def pagination(limit: int = 10, offset: int = 0): return {"limit": limit, "offset": offset} class PaginationClass: def __init__(self, limit: int = 10, offset: int = 0): self.limit, self.offset = limit, offset @app.get("/fn") def fn(p: dict = Depends(pagination)): return p @app.get("/cls") def cls(p: PaginationClass = Depends()): return {"limit": p.limit, "offset": p.offset} c = TestClient(app) print("function:", c.get("/fn?limit=3").json()) print("class :", c.get("/cls?limit=3").json()) print() print("Identical behaviour. Reach for the class when it holds something.")

class RequireRole: def __init__(self, role: str): self.role = role def __call__(self, x_token: str = Header(default="")): ... require_admin = RequireRole("admin") require_reader = RequireRole("reader")

class RequireScope: def __init__(self, *scopes): self.scopes = set(scopes) def __call__(self, user: User = Depends(current_user)): missing = self.scopes - set(user.scopes) if missing: raise HTTPException(403, "Missing scope(s): %s" % ", ".join(sorted(missing))) return user read_modules = RequireScope("modules:read") write_modules = RequireScope("modules:read", "modules:write")

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.

Class Dependencies

Overview

Callables, not functions

Worth knowing