Global dependencies in FastAPI - Deep Dive

Overview - Global dependencies

What is it?

Global dependencies in FastAPI are functions or classes that provide shared resources or logic to many parts of an application. They are declared once and automatically used by multiple routes or components without repeating code. This helps keep your code clean and consistent by centralizing common tasks like authentication or database access. Essentially, they act like helpers that every part of your app can use easily.

Why it matters

Without global dependencies, you would have to repeat the same setup or checks in every route, which leads to mistakes and harder maintenance. Global dependencies solve this by letting you write shared logic once and apply it everywhere. This saves time, reduces bugs, and makes your app easier to update. Imagine having to check a user's login status in every page manually — global dependencies automate that for you.

Where it fits

Before learning global dependencies, you should understand basic FastAPI routes and how to use simple dependencies. After mastering global dependencies, you can explore more advanced topics like dependency overrides for testing, security schemes, and middleware integration. This topic fits in the middle of your FastAPI learning path, bridging simple dependencies and full app architecture.

Mental Model

Core Idea

Global dependencies are shared helpers automatically applied across many routes to avoid repeating common setup or checks.

Think of it like...

Think of global dependencies like a building's central heating system: instead of installing a heater in every room, one system warms the whole building efficiently and consistently.

┌─────────────────────────────┐
│        FastAPI App          │
│ ┌───────────────┐           │
│ │ Global        │           │
│ │ Dependency    │──────────▶│ Routes
│ │ (shared logic) │           │
│ └───────────────┘           │
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding FastAPI dependencies

Concept: Learn what dependencies are and how FastAPI uses them to share code.

In FastAPI, dependencies are functions or classes that provide data or logic to routes. You declare them with the Depends() function. For example, a function that returns the current user can be a dependency. Routes can then use this dependency to get the user without repeating code.

Result

You can reuse code like authentication or database access in multiple routes easily.

Understanding dependencies is key because global dependencies build on this concept to share logic app-wide.

2

Foundation

Declaring a simple dependency function

Concept: Create a basic dependency function and use it in a route.

Define a function that returns a value, then add it as a parameter with Depends() in a route. For example: def get_token(): return "token123" @app.get("/items") async def read_items(token: str = Depends(get_token)): return {"token": token} This passes the token to the route automatically.

Result

The route receives the token value without manual calls.

This shows how dependencies inject values, making code cleaner and more modular.

3

Intermediate

Applying dependencies globally to routes

🤔Before reading on: do you think global dependencies apply to all routes automatically or must be added to each route manually? Commit to your answer.

Concept: Learn how to apply dependencies to all routes in a router or app without repeating Depends() in every route.

FastAPI lets you add dependencies to an APIRouter or the main FastAPI app. For example: app = FastAPI(dependencies=[Depends(get_token)]) Now, every route in this app automatically uses get_token as a dependency. You don't need to add it to each route.

Result

All routes receive the dependency's output automatically.

Knowing you can apply dependencies globally saves repetition and enforces consistent behavior across routes.

4

Intermediate

Using global dependencies for authentication

🤔Before reading on: do you think global dependencies can handle errors like unauthorized access automatically? Commit to your answer.

Concept: Use global dependencies to enforce security checks like verifying user credentials on every request.

Define a dependency that checks a user's token and raises an error if invalid: def verify_token(token: str = Depends(get_token)): if token != "secret": raise HTTPException(status_code=401, detail="Unauthorized") app = FastAPI(dependencies=[Depends(verify_token)]) Now, every route requires a valid token or returns 401.

Result

Unauthorized requests are blocked globally without extra code in routes.

Global dependencies can enforce app-wide policies like security, improving safety and reducing mistakes.

5

Advanced

Combining global and route-specific dependencies

🤔Before reading on: do you think route-specific dependencies override or add to global dependencies? Commit to your answer.

Concept: Learn how global dependencies work together with dependencies declared on individual routes.

Global dependencies run for every route. Route-specific dependencies add extra logic only for that route. For example: app = FastAPI(dependencies=[Depends(global_check)]) @app.get("/special", dependencies=[Depends(special_check)]) async def special_route(): return {"msg": "special"} Both global_check and special_check run for /special, but only global_check runs for others.

Result

You get layered dependency checks, combining global and local logic.

Understanding this layering helps design flexible and secure APIs without duplication.

6

Advanced

Performance considerations with global dependencies

🤔Before reading on: do you think global dependencies run once per request or once per app startup? Commit to your answer.

Concept: Global dependencies run on every request, so heavy operations can slow down all routes.

If a global dependency does expensive work (like database queries), it affects all requests. To optimize, use caching or limit heavy logic to route-specific dependencies only where needed. Also, use async functions to avoid blocking.

Result

Better app performance and responsiveness by managing dependency workload.

Knowing the cost of global dependencies prevents slowdowns and helps scale apps efficiently.

7

Expert

Overriding global dependencies for testing

🤔Before reading on: do you think global dependencies can be replaced during tests without changing app code? Commit to your answer.

Concept: FastAPI allows replacing global dependencies with mocks or test versions during testing to isolate behavior.

Use app.dependency_overrides to swap global dependencies: app.dependency_overrides[get_token] = lambda: "test-token" This makes tests use the mock token without changing production code. It enables reliable and fast tests.

Result

Tests run with controlled dependencies, improving test quality and speed.

Understanding dependency overrides unlocks powerful testing strategies without code duplication.

Under the Hood

FastAPI uses Python's dependency injection system. When a request comes in, FastAPI inspects the route's parameters and global dependencies. It calls each dependency function in order, resolving their return values and passing them to the route handler. Global dependencies are stored in the app or router and automatically included in this process. This happens per request, ensuring fresh data or checks each time.

Why designed this way?

FastAPI's design aims for explicit, fast, and easy-to-understand dependency injection. Global dependencies reduce boilerplate and enforce consistency. The per-request call ensures dependencies can react to request data dynamically. Alternatives like global singletons or middleware were less flexible or more complex to manage. This approach balances clarity, performance, and flexibility.

┌───────────────┐
│ HTTP Request  │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ FastAPI Router│
│ with Global   │
│ Dependencies  │
└──────┬────────┘
       │ Calls global dependencies
       ▼
┌───────────────┐
│ Dependency    │
│ Functions     │
└──────┬────────┘
       │ Pass results
       ▼
┌───────────────┐
│ Route Handler │
│ Function      │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do global dependencies run only once when the app starts or on every request? Commit to your answer.

Common Belief: Global dependencies run once at app startup and then reuse their results for all requests.

Reality: Global dependencies run on every request to provide fresh data or checks each time.

Why it matters: Assuming they run once can lead to stale data or security holes if dependencies cache sensitive info incorrectly.

Quick: Can global dependencies replace middleware for all cross-cutting concerns? Commit to your answer.

Common Belief: Global dependencies can do everything middleware does, so middleware is unnecessary.

Reality: Global dependencies handle dependency injection and checks but middleware is better for low-level request/response processing like headers or CORS.

Why it matters: Misusing global dependencies instead of middleware can cause design confusion and harder maintenance.

Quick: Do route-specific dependencies override global dependencies or run alongside them? Commit to your answer.

Common Belief: Route-specific dependencies override and replace global dependencies for that route.

Reality: Route-specific dependencies run in addition to global dependencies; they do not replace them.

Why it matters: Misunderstanding this leads to missing important global checks or duplicated logic.

Quick: Can you use global dependencies to share state between requests? Commit to your answer.

Common Belief: Global dependencies can store and share state across requests like global variables.

Reality: Global dependencies run per request and should not be used to share mutable state between requests.

Why it matters: Trying to share state this way causes bugs and concurrency issues in web apps.

Expert Zone

1

Global dependencies run in the order they are declared, which can affect side effects and error handling.

2

Dependencies can themselves depend on other dependencies, creating a dependency tree that FastAPI resolves automatically.

3

Using async dependencies globally requires careful handling to avoid blocking the event loop and degrading performance.

When NOT to use

Avoid global dependencies for very heavy or slow operations that don't need to run on every request; use route-specific dependencies or caching instead. For low-level request/response manipulation, use middleware. For sharing state across requests, use external stores like databases or caches.

Production Patterns

In production, global dependencies often enforce authentication, logging, or database session management. They are combined with route-specific dependencies for fine-grained control. Dependency overrides enable seamless testing and staging environments without code changes.

Connections

Middleware

Complementary pattern for request processing

Understanding global dependencies alongside middleware clarifies how to separate concerns: dependencies inject data and logic, middleware handles low-level request/response tasks.

Dependency Injection (general programming)

Builds on the general idea of injecting dependencies to improve modularity

Knowing global dependencies in FastAPI deepens understanding of dependency injection as a design pattern that improves code reuse and testability.

Centralized Authentication Systems

Global dependencies often implement centralized authentication logic

Seeing global dependencies as a way to centralize authentication helps appreciate their role in security architecture.

Common Pitfalls

#1 Adding heavy database queries in a global dependency causing slow responses.

Wrong approach:

app = FastAPI(dependencies=[Depends(expensive_db_query)])

def expensive_db_query():
# Simulate slow query
import time
time.sleep(5)
return "data"

Correct approach:

Use caching or move expensive_db_query to route-specific dependencies only where needed.

@app.get("/data")
async def get_data(data=Depends(expensive_db_query)):
return {"data": data}

Root cause:

Misunderstanding that global dependencies run on every request and affect all routes.

#2 Expecting global dependencies to share mutable state between requests.

Wrong approach:

shared_list = []

def global_dep():
shared_list.append(1)
return shared_list

app = FastAPI(dependencies=[Depends(global_dep)])

Correct approach:

Use external storage like a database or cache to share state safely between requests.

Root cause:

Confusing per-request dependency calls with global shared variables.

#3 Trying to override global dependencies by redeclaring them in routes expecting replacement.

Wrong approach:

@app.get("/test", dependencies=[Depends(new_dep)])
async def test_route():
return {"msg": "test"}

Correct approach:

Use app.dependency_overrides to replace global dependencies during testing or special cases.

Root cause:

Misunderstanding that route dependencies add to, not replace, global dependencies.

Key Takeaways

Global dependencies let you share common logic across all routes without repeating code.

They run on every request, so keep them efficient and avoid heavy operations globally.

Global dependencies combine with route-specific ones to create layered, flexible behavior.

You can override global dependencies during testing to isolate and control app behavior.

Understanding global dependencies helps build secure, maintainable, and clean FastAPI applications.