Http2 - Uvicorn

Uvicorn has experimental support for HTTP/2, built on the zttp parser.
Experimental Feature
HTTP/2 support is currently experimental and is not enabled by default.
HTTP/2 introduces several key features:
HTTP/2 support requires the zttp package:
To enable it, select the zttp HTTP implementation and pass --http2:
The --http2 option makes zttp serve both HTTP versions. Each connection is dispatched to HTTP/1.1 or HTTP/2 depending on what the client speaks. Without this option, zttp serves HTTP/1.1 only. This default keeps experimental HTTP/2 support opt-in.
When using HTTPS, HTTP/2 is negotiated via ALPN (Application-Layer Protocol Negotiation) during the TLS handshake. This is the most common way to use HTTP/2, and the only one web browsers support.
For testing it locally, you can generate a self-signed certificate:
Then create a simple ASGI application:
Run Uvicorn with --http zttp --http2 and the SSL certificate files:
You can test the connection using curl (-k skips certificate verification for self-signed certs):
On cleartext connections, Uvicorn accepts clients that speak HTTP/2 directly - known as "prior knowledge" h2c. The client opens the connection with the HTTP/2 preface instead of an HTTP/1.1 request, and Uvicorn switches protocols on the spot.
Using the same main.py:
This is the mechanism proxies use for cleartext HTTP/2 upstreams, so HTTP/2 between a proxy and Uvicorn works without TLS. How you enable it is proxy-specific: Traefik and Caddy use h2c:// upstream URLs, while Envoy configures HTTP/2 on the cluster.
Prior-knowledge h2c provides no transport encryption or peer authentication. Limit it to trusted private networks (e.g. the proxy-to-Uvicorn hop); use HTTP/2 over TLS for any untrusted hop.
The HTTP/1.1 Upgrade: h2c mechanism is not supported: an upgrade request is served as plain HTTP/1.1, which RFC 7540 explicitly allows. Browsers do not support h2c at all - they only speak HTTP/2 over TLS.
When a request comes in over HTTP/2, the ASGI scope has http_version set to "2":
Uvicorn advertises the http.response.early_hint ASGI extension for HTTP/2 requests. You can send one or more 103 Early Hints responses before the final response:
Each value in links becomes a separate Link header in the 103 response.
In production, Uvicorn is typically deployed behind a reverse proxy like Nginx, Caddy, or HAProxy. The proxy can terminate TLS and serve HTTP/2 to clients, while talking either HTTP/1.1 or HTTP/2 to Uvicorn.
HTTP/2 upstream refers to the protocol used between the proxy and Uvicorn. While all modern proxies support HTTP/2 for client connections, support for HTTP/2 to backend servers varies.
Multiplexing is HTTP/2's ability to send multiple requests simultaneously over a single TCP connection. Some proxies support HTTP/2 upstream but open a new connection per request, which means they don't truly multiplex.
Here's the state of proxy support at the time of writing:
Uvicorn supports both upstream flavors: cleartext prior-knowledge h2c, and HTTP/2 over TLS via ALPN when the proxy-to-Uvicorn hop uses TLS.
HTTP/2 provides the most benefit when:
For internal, low-latency connections (like proxy to backend), HTTP/1.1 with keepalive often performs comparably to HTTP/2. It is simpler to configure and debug, which is why it remains the recommended default for most deployments.
Trailers are headers you send after the response body. You can use them for values that become available while streaming, such as a checksum or final processing statistics, without buffering the entire response first.
They also let you serve ASGI applications that implement gRPC, which reports call results through grpc-status and optional grpc-message trailers.
Your client must send TE: trailers to receive them. Set more_trailers=True to send more than one trailer message; Uvicorn combines their headers and completes the response on the last message.
The implementation is young, and some protocol features are not complete yet: