# uvicorn Settings Reference

!!! info "Primary sources"
    - [uvicorn settings](https://uvicorn.dev/settings/)
    - [uvicorn deployment](https://uvicorn.dev/deployment/)

---

## Configuration Methods

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

```bash
# 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 "Environment file scope"
    `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

```bash
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):

```dockerfile
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)

```bash
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)

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

Nginx config headers to set:
```nginx
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 |