uvicorn

TLDR

Run ASGI application

$ uvicorn [main:app]

Run with auto-reload

$ uvicorn [main:app] --reload

Bind to specific host and port

$ uvicorn [main:app] --host [0.0.0.0] --port [8000]

Run with multiple workers

$ uvicorn [main:app] --workers [4]

Run with SSL

$ uvicorn [main:app] --ssl-keyfile [key.pem] --ssl-certfile [cert.pem]

Use specific loop (uvloop for performance)

$ uvicorn [main:app] --loop uvloop

Run with Unix socket

$ uvicorn [main:app] --uds [/tmp/uvicorn.sock]

Specify log level

$ uvicorn [main:app] --log-level [debug]

SYNOPSIS

uvicorn app [--host host] [--port port] [--reload] [--workers num] [options]

uvicorn is a lightning-fast ASGI server for Python. It serves async web frameworks like FastAPI, Starlette, and others that implement the ASGI specification.
ASGI (Asynchronous Server Gateway Interface) enables async/await handling of HTTP, WebSocket, and other protocols. Uvicorn implements the server side, connecting to async application code.
Development mode (--reload) watches files and restarts on changes. This enables rapid iteration without manual server restarts.
Production deployments use multiple workers (--workers) to utilize CPU cores. Each worker is a separate process handling requests independently. Process management handles worker crashes.
Performance comes from optional uvloop (libuv-based event loop) and httptools (HTTP parsing). These C-based libraries significantly outperform pure Python implementations.
WebSocket support enables real-time bidirectional communication. The server handles connection upgrades and message routing to application code.

PARAMETERS

--host HOST

Bind socket to host (default: 127.0.0.1).

--port PORT

Bind socket to port (default: 8000).

--uds PATH

Bind to Unix domain socket.

--fd NUM

Bind to socket from file descriptor.

--reload

Enable auto-reload on code changes.

--reload-dir PATH

Directories to watch for reload.

--reload-include PATTERN

Include patterns for reload.

--reload-exclude PATTERN

Exclude patterns from reload.

--workers NUM

Number of worker processes.

--loop IMPL

Event loop: auto, uvloop, asyncio.

--http IMPL

HTTP implementation: auto, h11, httptools.

--ws IMPL

WebSocket implementation: auto, websockets, wsproto.

--interface TYPE

Interface: auto, asgi3, asgi2, wsgi.

--log-level LEVEL

Log level: critical, error, warning, info, debug, trace.

--access-log / --no-access-log

Enable/disable access log.

--ssl-keyfile PATH

SSL key file.

--ssl-certfile PATH

SSL certificate file.

CAVEATS

Workers share nothing - state must use external storage. Reload mode shouldn't be used in production. uvloop not available on Windows. SSL termination often better at reverse proxy. File uploads limited by memory.

HISTORY

uvicorn was created by Tom Christie (creator of Django REST framework and Starlette) around 2017. It implements the ASGI spec that enables async Python web frameworks. The name references UV (high-energy light) and the suffix -corn common in Python web servers.