A worker (worker) is a server process that handles incoming HTTP requests to your FastAPI application.
Think of it as a person at a customer service counter:
the more workers you have, the more customers you can serve at the same time.
Imagine you have an API that processes requests like:
@app.get("/procesar") def procesar(): time.sleep(2) return {"mensaje": "I am done"}
If you have 1 worker, you can only process 1 request every 2 seconds.
If you have 4 workers, you can process 4 requests in parallel, one per process.
FastAPI does not directly manage the workers, but rather the ASGI server that executes your application.
The most commonly used is Uvicorn, and sometimes it’s combined with Gunicorn in production environments.
Increasing workers with Uvicorn
If you run FastAPI with Uvicorn directly, you can use the option --workers:
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
- This will launch 4 processes of your application in parallel.
- Ideal for making use of multiple CPU cores.
<
blockquote class=”wp-block-quote is-layout-flow wp-block-quote-is-layout-flow”>
Do not use more workers than what your server can handle, as each process uses additional memory.
Away to increase workers in Docker
If your application runs inside a Docker container, you can edit the CMD of the Dockerfile:
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]
Or make it automatic based on available cores::
CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port 8000 --workers $((2 * $(nproc) + 1))"]
$$(nproc)detects the number of CPUs in the container.2 * $$(nproc) + 1is a common rule in web servers (inspired by Gunicorn).
Increase workers with Gunicorn + Uvicorn
For production environments (e.g., Ubuntu or AWS), it is recommended to use Gunicorn as the main manager and Uvicorn as the worker:
gunicorn -k uvicorn.workers.UvicornWorker main:app --workers 4 --bind 0.0.0.0:8000
Important parameters:
-k uvicorn.workers.UvicornWorker: indicates that Gunicorn should use Uvicorn.
--workers: número of processes (equal to before).
--bind: address and port where it listens.
A general rule is:
workers = 2 * cores_CPU + 1
If your server has 2 cores → 2 * 2 + 1 = 5 workers
But if your application is memory-hungry or does heavy tasks, it may be more convenient to use less.
Verification
You can verify how many workers are running with a command like:
ps aux | grep uvicorn
You’ll see several lines if there are multiple workers active.
Command Table:
| Environment | Command or Configuration |
|---|---|
| Local (Uvicorn) | uvicorn main:app --workers 4 |
| Dockerfile | CMD ["uvicorn", "main:app", "--workers", "4"] |
| Gunicorn | gunicorn -k uvicorn.workers.UvicornWorker main:app --workers 4 --bind 0.0.0.0:8000 |
| General Rule | workers = 2 * núcleos_CPU + 1 |
