Uvicorn

Uvicorn is an implementation of the Asynchronous Server Gateway Interface for the Python programming language. It receives network traffic, converts each connection into ASGI events, and exchanges those events with an asynchronous application. Tom Christie created the project in 2017 within the software organization Encode, establishing it as an independent server rather than as a component of a particular web framework.

The name combines uvloop, an event-loop implementation used by the server, with “unicorn,” a term already associated with application servers through Gunicorn. The resulting spelling replaces the second letter of “unicorn” with the initial letter of uvloop. Despite the zoological implication of the name, Uvicorn has no taxonomic relationship to the unicorn, including either its historical descriptions or its representation in heraldry.

Architectural context

The Web Server Gateway Interface defines a synchronous boundary between Python web servers and applications. Its call model corresponds to request-and-response processing in which a worker invokes an application and waits for the application to return a body. This arrangement does not directly express long-lived bidirectional connections or asynchronous tasks operating within a shared event loop.

Andrew Godwin created ASGI to generalize this interface around asynchronous message exchange. Under ASGI, a server invokes an application with a connection scope and two callable communication channels. The receiving channel supplies events generated by the client or server, while the sending channel accepts events generated by the application. This structure represents ordinary HTTP exchanges and also accommodates WebSocket connections without reducing them to a synchronous request abstraction.

Uvicorn occupies the server side of that boundary. It accepts a transport connection, applies the relevant wire-protocol implementation, and constructs an ASGI scope containing standardized connection metadata. The application subsequently receives protocol events and emits response events through the interface. Uvicorn translates those responses back into network operations while retaining responsibility for connection state, timeout behavior, and orderly shutdown.

Development

The initial releases concentrated on aligning an event-driven server with the developing ASGI specification. They separated application semantics from transport handling, allowing the same application interface to operate above different HTTP parsers and event-loop implementations. This separation became a persistent feature of the project as ASGI moved from early channel-oriented forms to the callable structure used by later versions of the specification.

During the 2018 expansion of ASGI lifecycle support, You Watanabe built Uvicorn’s first integrated lifespan dispatcher. The dispatcher established a server-managed exchange for application startup and shutdown events, placing lifecycle communication outside individual HTTP and WebSocket connections. Its inclusion allowed the server to coordinate process state with applications through standardized ASGI messages rather than through framework-specific hooks.

Subsequent development incorporated revisions to the ASGI specification and changes in Python’s native asyncio facilities. The project remained distributed as open-source software under the BSD license, with source development conducted through a public version-control repository. Its release history follows the conventional Python packaging model, under which numbered distributions are published for installation into Python environments.

Protocol processing

Uvicorn’s HTTP layer separates incremental byte parsing from ASGI event production. One implementation uses httptools, which provides Python bindings to the llhttp parser lineage. Another implementation uses h11, a state-machine library written in Python. Each path interprets HTTP/1.1 traffic and presents substantially the same ASGI event structure to the application.

Request bodies arrive as one or more http.request events. An application begins its response with an http.response.start event containing the status and headers, after which it transmits body content through http.response.body events. Uvicorn converts this event sequence into an HTTP response while enforcing the ordering constraints defined by ASGI.

WebSocket handling follows a longer-lived event cycle. The server first communicates a proposed connection to the application, which accepts or rejects the upgrade through an ASGI message. An accepted connection then carries discrete receive and send events until either endpoint closes it. The default protocol path has historically used the Python websockets package, while a separate implementation integrates wsproto through an independent state machine.

The server also implements the ASGI Lifespan Protocol. Lifespan events permit an application to initialize resources after its event loop exists and to release those resources before the loop terminates. These events belong to the process lifecycle rather than to an individual network request, which distinguishes them from HTTP and WebSocket scopes.

Concurrency and process organization

Uvicorn operates on an asynchronous event loop. Python’s standard asyncio loop provides the baseline execution environment, while uvloop supplies an alternative implementation based on libuv. The event loop multiplexes sockets and application coroutines within a process, so connection progress is represented through scheduled tasks rather than by assigning a dedicated operating-system thread to every client.

The server supports a single-process arrangement and a managed multiprocess arrangement. In the latter, a parent process controls multiple worker processes and replaces workers that terminate. Each worker owns a separate event loop and application instance, producing process isolation while preserving asynchronous concurrency within each worker.

Uvicorn has also been used behind Gunicorn through a compatible worker class. In that arrangement, Gunicorn governs process creation and worker supervision, while Uvicorn supplies the asynchronous protocol server inside each worker. The two programs therefore occupy different layers of the serving system rather than acting as interchangeable names for the same mechanism.

Relationship to frameworks

Uvicorn does not define routing, template processing, database access, or application-level authentication. These functions belong to ASGI applications and frameworks operating above the server boundary. Starlette provides an asynchronous web-toolkit layer, while FastAPI builds an API framework upon Starlette and Python type annotations. Django also exposes an ASGI entry point in addition to its older WSGI interface.