uvicorn Settings Reference¶

Configuration Methods¶

Three equivalent approaches (CLI takes precedence over env vars):

# 1. CLI flags
uvicorn main:app --host 0.0.0.0 --port 8000

# 2. UVICORN_* environment variables
export UVICORN_HOST=0.0.0.0
export UVICORN_PORT=8000
uvicorn main:app

# 3. Programmatic (dev/test only)
uvicorn.run("main:app", host="0.0.0.0", port=8000)

All Settings by Category¶

Socket Binding¶

Production¶

Logging¶

Implementation¶

HTTP / Proxy Headers¶

Resource Limits¶

Timeouts¶

Development¶

Application¶

Recommended Production CMD¶

uvicorn my_app.main:app \
    --host 0.0.0.0 \
    --port 8000 \
    --workers 1 \
    --loop auto \
    --http auto \
    --log-level info \
    --proxy-headers \
    --forwarded-allow-ips '*' \
    --timeout-graceful-shutdown 30

In a Dockerfile (exec form):

CMD ["uvicorn", "my_app.main:app",
     "--host", "0.0.0.0",
     "--port", "8000",
     "--workers", "1",
     "--proxy-headers",
     "--forwarded-allow-ips", "*",
     "--timeout-graceful-shutdown", "30"]

Process Manager Options¶

Built-in multi-worker (Docker Compose / single host)¶

uvicorn my_app.main:app --workers 4

The built-in manager spawns workers, monitors their health, and auto-restarts crashed workers. Signal support: - SIGHUP — rolling graceful restart (deploy new code without dropping requests) - SIGTTIN — add one worker - SIGTTOU — remove one worker

Behind Nginx (UNIX socket)¶

uvicorn my_app.main:app --uds /tmp/uvicorn.sock --proxy-headers

Nginx config headers to set:

proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

uvicorn[standard] vs bare uvicorn¶

Use uvicorn[standard] in all environments. The [standard] extras are also included when you install fastapi[standard].

Anti-patterns¶