Uvicorn Workers: Scaling Your FastAPI App

WHY IT EXISTS The default uvicorn main:app command is great for development but creates a major bottleneck in production. It runs a single process on a single CPU core, leaving the rest of your server's processing power unused and limiting how many requests you can handle at once. To serve real traffic, you need to run multiple processes.

THE MENTAL MODEL A single Uvicorn process is like a restaurant with only one chef who takes orders, cooks, and serves. Adding workers is like hiring more chefs. Each chef (worker process) can handle their own set of orders independently, dramatically increasing the restaurant's (your app's) capacity to serve customers (users). The master process acts as the host, distributing incoming customers to the available chefs.

HOW IT WORKS Uvicorn is an ASGI server that runs your FastAPI application. When you run it with the --workers flag, it starts a master process that manages several child "worker" processes. The master process listens for incoming network requests and distributes them among the available workers. Each worker is a separate Python process running its own instance of your FastAPI app, capable of handling a request from start to finish. This allows your application to process multiple requests simultaneously across different CPU cores.

WHEN TO USE IT Use Uvicorn workers for any production deployment of a FastAPI application. It is the primary mechanism for scaling on a single machine. A common rule of thumb for CPU-bound tasks is to start with a number of workers equal to the number of CPU cores. For I/O-bound tasks, the formula (2 * number of CPU cores) + 1 is a popular starting point. Always benchmark to find the optimal count for your specific workload.

WHEN NOT TO USE IT Do not use multiple workers during early development or debugging. The single-process mode is simpler, provides clearer tracebacks, and supports features like auto-reloading (--reload) that are disabled in a multi-process setup. Using workers also won't fix application logic that is fundamentally slow or blocking; you still need to write efficient async code.

ONE CANONICAL EXAMPLE While the development server is started with uvicorn main:app --reload, a production-ready server on a machine with 4 CPU cores might be started with the command: uvicorn main:app --host 0.0.0.0 --port 8000 --workers 9. This command tells Uvicorn to start 9 worker processes, listen on all available network interfaces on port 8000, and serve the FastAPI application defined in the app object inside the main.py file.