FastAPI: Mounting Independent Sub-Applications

Why it exists

Mounting solves the problem of composing multiple, fully independent web services into a single, unified API. Instead of running separate services on different ports or domains, you can present them as different path prefixes under one host, simplifying deployment, routing, and client interaction.

The mental model

Think of mounting like plugging a self-contained power strip into a wall outlet. The wall outlet (the main app) provides a connection point at a specific path (e.g., /sub-app), but the power strip (the sub-app) manages all its connected devices independently. The sub-app has its own circuit breaker (exception handlers) and features (API docs), and it doesn't know or care what else is happening in the main application.

How it works

You create two or more FastAPI application instances. In your main app, you call the .mount() method, providing a path prefix as the first argument (e.g., "/sub") and the sub-application object as the second. FastAPI then directs any incoming request starting with that prefix to the sub-application. The sub-app processes the request as if the prefix didn't exist, using its own routing, dependencies, and middleware. Each app generates its own OpenAPI schema, resulting in separate API docs (e.g., /docs for the main app and /sub/docs for the sub-app).

When to use it

Use mounting when you need strong isolation between parts of your application. It's perfect for a microservices-style architecture where a gateway app mounts several backend services. It's also useful in a "modular monolith" to enforce strict boundaries between different business domains, preventing them from sharing code or state implicitly.

When not to use it

Don't use mounting if you need to share dependencies, middleware, or configuration between application components. If your components are tightly coupled and need to interact with a shared state or use common utility functions via dependency injection, using an APIRouter and including it in the main app is the correct pattern. Mounting creates isolation, which is counterproductive in that scenario.

One canonical example

Imagine a main application that also needs to serve a completely separate admin panel API. You would define the main app and the admin app as two distinct FastAPI instances. Then, in your main application file, you would mount the admin app:

from fastapi import FastAPI

from admin_panel import admin_app # admin_app is a separate FastAPI() instance

app = FastAPI()

@app.get("/users/me")

def read_current_user():
return {"user_id": "the_current_user"}

app.mount("/admin", admin_app)

A request to /users/me is handled by the main app. A request to /admin/dashboard is routed to the admin_app instance. The API docs would be available at /docs (main app) and /admin/docs (admin app).