Uvicorn reload vs Gunicorn Uvicorn workers: trade‑off for resource‑constrained production

Answer first

Do not use Uvicorn --reload in production. Use Gunicorn with Uvicorn workers for any container that is subject to CPU/memory limits and must serve traffic reliably.

There is no documented universal CPU or memory ceiling at which the reload watcher becomes unacceptable, and there is no fixed concurrency level where Gunicorn workers become measurably better. Both thresholds are workload and container specific and must be measured for your app.

Confirmed facts

• Uvicorn --reload is development only. It runs a parent watcher process that spawns a child application process and restarts the child on detected file changes.
• The watcher adds an extra process, continuous filesystem polling via inotify, extra CPU churn on events, and additional file descriptors per watched path.
• Gunicorn with Uvicorn workers removes the reload watcher. It provides a process manager with multiple Uvicorn worker processes, process-level isolation, and graceful restarts. It adds Gunicorn manager overhead and per-worker memory overhead.
• In a production container with an immutable image the expected file-system change rate is zero. Any non-zero rate is a signal of writable volumes, logs, tmp writes, or orchestrator updates.

Likely explanation

Acceptability of the watcher depends on container CPU shares, memory limit, base application footprint, size of the watched directory tree, and OS inotify limits. In resource-constrained containers the watcher overhead can become material relative to the app budget and can contribute to FD exhaustion or OOM kills.

The likelihood of watcher-triggered restarts rises with the rate of filesystem changes per minute. With zero changes the watcher is idle but still consumes resources. With changes from logs, writable volumes, or tmp files the watcher can cause spurious reload loops and repeated cold starts in production.

Measurable latency and stability improvements from the Gunicorn worker model versus a single-process Uvicorn with reload typically appear when concurrent request load exceeds what one asyncio worker can sustain reliably for your specific handlers, I/O patterns, and container limits. The exact concurrency level cannot be given as a fixed number without profiling.

Steps needed for this case

1. Disable reload for production. Run Uvicorn without --reload or run Gunicorn with Uvicorn workers.
2. Measure baseline in the target container: CPU, memory, open FDs, and inotify watches with reload off, then compare with reload on under idle and load.
3. Monitor inotify watches and open FDs inside the container during normal operation to quantify watcher cost and detect spurious file events.
4. Perform controlled load tests varying concurrent connections for single-process Uvicorn versus Gunicorn with Uvicorn workers and compare latency percentiles and error rates.

To give a concrete ceiling for your setup, provide the container CPU shares / millicores and memory limit, the size of the watched tree, and the observed file change rate per minute from logs/volumes. That changes the recommendation on worker count and whether any watcher can be tolerated at all.