Uvicorn

Uvicorn is an ASGI (Asynchronous Server Gateway Interface) server implementation for Python. Where WSGI servers like Gunicorn only handle synchronous request/response cycles, Uvicorn provides the low-level server loop that async Python web frameworks need to support long-lived connections such as WebSockets and long-polling HTTP, plus the standard startup/shutdown lifespan protocol.

It ships as both a CLI (uvicorn app:app) and a programmatic API (uvicorn.run(app)), and is the de facto standard server underneath FastAPI, Starlette, and other ASGI frameworks. Installing the standard extras pulls in Cython-accelerated dependencies — uvloop for the event loop and httptools for HTTP parsing — for substantially better throughput than the pure-Python fallback.

What You Get

• An ASGI-compliant HTTP/1.1 and WebSocket server runnable via CLI (uvicorn app:app) or embedded with uvicorn.run()
• Pluggable protocol implementations — h11/httptools for HTTP, websockets/wsproto for WebSockets, asyncio/uvloop for the event loop
• Application lifespan protocol support for startup/shutdown hooks
• A --reload development mode backed by watchfiles for fast local iteration
• Multi-worker process supervision and graceful shutdown handling for production deployments
• SSL/TLS termination, Unix domain socket and file-descriptor binding for containerized and proxied setups

Common Use Cases

• Running a FastAPI or Starlette application in local development with hot reload
• Serving an ASGI app in production behind a reverse proxy such as Nginx or Traefik
• Powering WebSocket-based realtime features (chat, live updates, streaming responses) in async Python apps
• Embedding a server directly inside a script or worker process via uvicorn.run() instead of a CLI invocation
• Running multiple worker processes for CPU-bound concurrency alongside async I/O concurrency

Under The Hood

Architecture

Uvicorn’s core execution path runs through uvicorn/main.py (the CLI entry main() and the run() convenience function), which builds a Config object (uvicorn/config.py) from CLI flags or kwargs, resolving protocol implementations (h11/httptools for HTTP, websockets/wsproto for WebSockets) and loop factories (asyncio/uvloop) via dotted-path lookups in dictionaries like HTTP_PROTOCOLS, WS_PROTOCOLS, and LOOP_FACTORIES. The Server class (uvicorn/server.py) owns the actual asyncio event loop: run() calls asyncio_run(self.serve()), which creates one asyncio.Protocol instance per connection via loop.create_server(create_protocol, ...), tracks connection and task state in a shared ServerState, and drives a lifespan handler (uvicorn/lifespan/on.py or off.py) that sends ASGI lifespan startup/shutdown events to the application before and after serving. Multi-worker setups (uvicorn/supervisors/multiprocess.py) fork worker processes that share listening sockets, while uvicorn/supervisors/basereload.py and watchfilesreload.py implement the --reload development loop.

Tech Stack

Written in modern Python (3.10+) targeting CPython and PyPy, with click for CLI argument parsing and h11 as its baseline pure-Python HTTP/1.1 parser (both required dependencies). The optional standard extra pulls in Cython-accelerated httptools for HTTP parsing, uvloop for a faster event loop (non-Windows only), websockets/wsproto for WebSocket protocol handling, watchfiles for reload-mode file watching, python-dotenv for --env-file support, and PyYAML for YAML logging config. Build tooling is hatchling with uv for dependency/dev-env management (a committed uv.lock), ruff for linting, mypy for type checking, and pytest (with pytest-xdist and pytest-codspeed for benchmarks) for testing.

Code Quality

The tests/ directory contains 38 test files covering protocols, supervisors, middleware, and the importer, with pytest-mock and trustme (for TLS test certs) as dev dependencies, and coverage is configured with fail_under = 100 in pyproject.toml — an unusually strict bar signaling a mature, disciplined test suite. Source files use full type annotations (from __future__ import annotations, TYPE_CHECKING guards for expensive imports like protocol implementations in server.py), and mypy runs as part of CI. Naming and module layout are consistent, with one file per protocol/loop/supervisor variant, and error handling in server.py’s shutdown()/_wait_tasks_to_complete() explicitly bounds graceful-shutdown waits with asyncio.wait_for and a timeout, falling back to task cancellation rather than hanging indefinitely.

API Design Uvicorn’s public surface is intentionally small: a Config object, a Server class, and a run() convenience function that most users never go beyond. Getting started is a single line — uvicorn.run(app) or uvicorn app:app from the CLI — with sensible defaults (auto-detecting the best available HTTP/WS/loop implementation) and progressive disclosure via CLI flags or Config kwargs for anything more advanced (SSL, workers, reload, logging). Documentation is thorough (a full mkdocs site with settings/concepts/deployment pages under docs/), and CLI help text is generated from the same Config definitions the programmatic API uses, keeping the two surfaces consistent.