prompts/skills/fastapi-uv-docker/references/uvicorn-settings.md

uvicorn Settings Reference

Source: https://uvicorn.dev/settings/ | https://uvicorn.dev/deployment/

---

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)

Note: UVICORN_* env vars cannot be used from within an --env-file. The --env-file flag is for the ASGI application's config, not uvicorn's own config.

---

All Settings by Category

Socket Binding

Flag	Default	Notes
--host <str>	127.0.0.1	Use 0.0.0.0 in containers to bind all interfaces
--port <int>	8000	Use 0 to auto-pick an available port
--uds <path>	—	UNIX domain socket path (use behind Nginx)
--fd <int>	—	Inherit socket from file descriptor (use with Supervisor)

Production

Flag	Default	Notes
--workers <int>	1 (or $WEB_CONCURRENCY)	Mutually exclusive with --reload
--env-file <path>	—	Env file for the application (not uvicorn itself)
--timeout-worker-healthcheck <int>	5	Seconds before killing a stuck worker

Logging

Flag	Default	Notes
--log-level <str>	info	critical, error, warning, info, debug, trace
--log-config <path>	—	.json or .yaml for dictConfig(); other formats use fileConfig()
--no-access-log	—	Disable access log without changing log level
--use-colors / --no-use-colors	auto	Force color on/off in log output

Implementation

Flag	Default	Notes
--loop <str>	auto	auto, asyncio, uvloop. uvloop requires uvicorn[standard]
--http <str>	auto	auto, h11, httptools. httptools requires uvicorn[standard]
--ws <str>	auto	auto, none, websockets, websockets-sansio, wsproto
--lifespan <str>	auto	auto, on, off
--ws-max-size <int>	16777216	WebSocket max message size in bytes (16 MB)
--ws-ping-interval <float>	20.0	WebSocket ping interval in seconds
--ws-ping-timeout <float>	20.0	WebSocket ping timeout in seconds

HTTP / Proxy Headers

Flag	Default	Notes
--proxy-headers	enabled	Trust X-Forwarded-For, X-Forwarded-Proto from trusted IPs
--no-proxy-headers	—	Disable proxy header trust entirely
--forwarded-allow-ips <list>	127.0.0.1	Comma-separated IPs/networks/literals to trust. Use '*' to trust all (safe in containers behind a trusted LB). Security risk if exposed directly to internet.
--root-path <str>	""	ASGI root_path for apps mounted below a URL prefix
--server-header / --no-server-header	enabled	Include/suppress Server response header
--date-header / --no-date-header	enabled	Include/suppress Date response header
--header <name:value>	—	Add custom default response headers (repeatable)

Resource Limits

Flag	Default	Notes
--limit-concurrency <int>	—	Max concurrent connections/tasks; returns HTTP 503 above this
--limit-max-requests <int>	—	Restart worker after N requests (limits memory leak accumulation)
--limit-max-requests-jitter <int>	0	Random jitter added to --limit-max-requests to stagger worker restarts
--backlog <int>	2048	Max queued connections under high load

Timeouts

Flag	Default	Notes
--timeout-keep-alive <int>	5	Close keep-alive connections after N seconds of inactivity
--timeout-graceful-shutdown <int>	—	Seconds to wait for in-flight requests to complete on SIGTERM before force-closing

Development

Flag	Default	Notes
--reload	False	Auto-reload on file changes. Never use in production. Mutually exclusive with --workers.
--reload-dir <path>	.	Directory to watch for changes (repeatable)
--reload-delay <float>	0.25	Seconds between reload checks
--reload-include <glob>	*.py	Patterns to include in watch (requires watchfiles)
--reload-exclude <glob>	.*, .py[cod], ...	Patterns to exclude from watch (requires watchfiles)

Application

Flag	Default	Notes
--factory	—	Treat APP as a () -> ASGI app callable (app factory pattern)
--app-dir <path>	.	Add to PYTHONPATH when resolving APP
--reset-contextvars	False	Run each request in a fresh contextvars.Context (asyncio only; workaround for a CPython context-leak bug)

---

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

Package	Extras included
uvicorn	Pure Python h11 HTTP, asyncio event loop
uvicorn[standard]	uvloop (faster event loop), httptools (faster HTTP parser), watchfiles (better reload), websockets, PyYAML (for --log-config)

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

---

Anti-patterns

Anti-pattern	Fix
--reload in Dockerfile CMD	Remove it — --reload is dev-only
--loop uvloop explicitly	Use --loop auto — it selects uvloop automatically when available
--http h11 explicitly in prod	Use --http auto — it selects httptools when available
uvicorn.run() at module level (no if __name__ == '__main__':)	Breaks multiprocessing workers; always guard it
Shell form CMD uvicorn ...	Exec form CMD ["uvicorn", ...] — required for SIGTERM to reach uvicorn