Parameters Reference

Every uvicorn.run() parameter with its type, options and default

Every argument of uvicorn.run() is keyword-only, except app. uvicorn.Config accepts the same arguments, except app_dir. Most of them have a command-line flag with dashes instead of underscores (ssl_keyfile becomes --ssl-keyfile). Each parameter has an anchor, for example /parameters/#ssl_context_factory.

Application

app

str | ASGI App

Your ASGI application. Can be a string in "module:attribute" format or the application object directly.

factory

bool

Treat app as an application factory (a callable that returns an ASGI app). Default: False

app_dir

str

Directory to add to sys.path when looking for the application module. Default: current working directory

reset_contextvars

bool

Run each ASGI request in a fresh contextvars.Context. Works around a context leak in asyncio (uvloop is not affected). Hides context set during lifespan from request handlers. Default: False

Socket Binding

host

str

Bind socket to this host. Use "0.0.0.0" to make the server available externally. Default: "127.0.0.1"

port

int

Bind socket to this port. Use 0 to bind to an available port. Default: 8000

uds

str

Bind to a UNIX domain socket instead of TCP. Useful for reverse proxy setups.

fd

int

Bind to socket from this file descriptor. Useful for socket activation.

Development

reload

bool

Enable auto-reload for development. Watches for file changes and restarts the server. Default: False

reload_dirs

list[str]

Directories to watch for file changes when reload is enabled.

reload_delay

float

Delay in seconds between detecting a change and reloading. Default: 0.25

reload_includes

list[str]

Glob patterns for files to include in reload watching. Requires watchfiles.

reload_excludes

list[str]

Glob patterns for files to exclude from reload watching. Requires watchfiles.

Production

workers

int

Number of worker processes. Reads from $WEB_CONCURRENCY env var if set. Cannot be used with reload. Send SIGHUP to restart workers one at a time without dropping requests. Default: 1

env_file

str

Path to environment configuration file to load.

timeout_worker_healthcheck

int

Timeout in seconds for worker health check. Default: 5

Logging

log_level

str

Logging level: "critical", "error", "warning", "info", "debug", "trace" (case-insensitive). Default: "info"

log_config

str | PathLike | dict

Logging configuration file path (.json, .yaml or .ini) or a dictionary config. YAML requires PyYAML.

access_log

bool

Enable or disable access logging. Default: True

use_colors

bool

Enable or disable colorized log formatting. Default: auto-detected

Protocol Implementation

loop

str

Event loop implementation: "auto", "asyncio", "uvloop", "zuvloop" (CPython 3.14+, installed separately), "none". Default: "auto"

http

str

HTTP protocol implementation: "auto", "h11", "httptools", "zttp" (experimental, requires the zttp package). Default: "auto"

http2

bool

Enable experimental HTTP/2. Requires http="zttp". h2c upgrade and WebSockets over HTTP/2 are not supported. Default: False

ws

str

WebSocket protocol implementation: "auto", "none", "websockets-sansio", "wsproto", "websockets" (legacy, deprecated). "auto" picks websockets-sansio when websockets is installed. Default: "auto"

lifespan

str

Lifespan protocol implementation: "auto", "on", "off". Default: "auto"

interface

str

Application interface type: "auto", "asgi3", "asgi2", "wsgi". Default: "auto"

h11_max_incomplete_event_size

int

Maximum size of incomplete HTTP events buffer (h11 only). Default: 16384

WebSocket Settings

ws_max_size

int

Maximum WebSocket message size in bytes. Default: 16777216 (16MB)

ws_max_queue

int

Maximum WebSocket receive queue length (legacy websockets implementation only). Default: 32

ws_ping_interval

float

WebSocket ping interval in seconds. Default: 20.0

ws_ping_timeout

float

WebSocket ping timeout in seconds. Default: 20.0

ws_per_message_deflate

bool

Enable WebSocket per-message compression (legacy websockets implementation only). Default: True

HTTP Settings

root_path

str

Set the ASGI root_path for applications mounted at a subpath. Default: ""

proxy_headers

bool

Enable X-Forwarded-Proto, X-Forwarded-For headers. Default: True

forwarded_allow_ips

str | list

Comma-separated list of trusted proxy IPs, networks or UNIX socket paths. Default: $FORWARDED_ALLOW_IPS, or "127.0.0.1" and "::1"

server_header

bool

Include "Server" header in responses. Default: True

date_header

bool

Include "Date" header in responses. Default: True

headers

list[tuple]

Custom HTTP headers to add to all responses.

HTTPS / SSL

ssl_keyfile

str

Path to SSL key file for HTTPS support.

ssl_certfile

str

Path to SSL certificate file for HTTPS support.

ssl_keyfile_password

str

Password to decrypt the SSL key file if encrypted.

ssl_version

int

SSL protocol version to use. Default: ssl.PROTOCOL_TLS_SERVER

ssl_cert_reqs

int

Whether client certificates are required. Default: ssl.CERT_NONE

ssl_ca_certs

str

Path to CA certificates file for client certificate verification.

ssl_ciphers

str

SSL ciphers to use. Default: None (OpenSSL's safe defaults)

ssl_context_factory

Callable

Function receiving (config, default_ssl_context_factory) and returning an ssl.SSLContext. Use it for mTLS, a minimum TLS version or in-memory certificates. Must be picklable with reload or workers.

Resource Limits

limit_concurrency

int

Maximum number of concurrent connections to allow before rejecting new connections.

limit_max_requests

int

Maximum number of requests per worker before terminating and respawning.

limit_max_requests_jitter

int

Jitter to add to limit_max_requests to stagger worker restarts and avoid all workers restarting simultaneously. Default: 0

backlog

int

Maximum number of pending connections in the connection backlog. Default: 2048

Timeouts

timeout_keep_alive

int

Timeout in seconds for keep-alive connections. Default: 5

timeout_graceful_shutdown

int

Timeout in seconds for graceful shutdown. After this time, connections are forcefully closed.