HTTP/2 - Gunicorn

HTTP/2 support is a beta feature introduced in Gunicorn 25.0.0. While it has been tested, the API and behavior may change in future releases. Please report any issues on GitHub.
Gunicorn supports HTTP/2 (RFC 7540) for improved performance with modern clients. HTTP/2 provides multiplexed streams, header compression, and other optimizations over HTTP/1.1.
HTTP/2 support requires:
Enable HTTP/2 by setting the --http-protocols option:
Or in a configuration file:
The order matters for ALPN negotiation - protocols are tried in order of preference.
Always include h1 as a fallback for clients that don't support HTTP/2.
HTTP/2 requires SSL/TLS. Configure certificates:
Or in a configuration file:
When TLS is terminated in front of Gunicorn - Cloud Run, fly.io, a service-mesh sidecar - the proxy can speak HTTP/2 to the upstream over plain TCP. Enable it with --http2-cleartext, on the gthread, gevent or asgi worker:
The value selects which mechanism is accepted: prior-knowledge, upgrade, both, or off (the default). Each mechanism is enabled separately, so turning one on does not turn the other on.
h2c is only accepted from peers in forwarded_allow_ips - the same trust list used for forwarded headers, which in this deployment shape is exactly the TLS-terminating proxy. A trusted peer that opens a connection with the HTTP/2 connection preface is served HTTP/2; anything else from a trusted peer (an HTTP/1.x request, a malformed or stalled preface) is rejected with a 400 rather than silently downgraded, so a misconfigured proxy fails loudly instead of quietly losing HTTP/2. Untrusted peers are served HTTP/1.1 exactly as if the flag were off.
Both mechanisms are served by the gthread, gevent and asgi workers. Note that with prior-knowledge alone a trusted peer sending anything else is refused with 400, while with upgrade or both an ordinary HTTP/1 request is served normally, because that is how an upgrade starts.
On the gthread and gevent workers, streams on an HTTP/2 connection are handled one after another, so a slow handler holds up the other streams on that connection; the asgi worker serves them concurrently. Request bodies are pulled from the connection as the application reads them and response bodies are streamed as the application produces them, so neither sits in worker memory. A stream that makes no progress for timeout seconds is cancelled, and a connection with nothing open is closed after keepalive.
As on HTTP/1, responses that cannot carry a body (HEAD, 1xx, 204, 304) send none, and sendfile() does not apply to HTTP/2 responses: raw file bytes would bypass HTTP/2 framing.
Test prior knowledge with:
h2c is cleartext. Only enable it behind a trusted, TLS-terminating proxy. Never expose an h2c port directly to the internet.
Fine-tune HTTP/2 behavior with these settings:
Example configuration:
Not all workers support HTTP/2:
If you use the sync or tornado worker with HTTP/2 enabled, Gunicorn will log a warning and fall back to HTTP/1.1.
For HTTP/2, the gthread worker is recommended:
Gunicorn supports HTTP 103 Early Hints (RFC 8297), allowing servers to send resource hints before the final response. This enables browsers to preload CSS, JavaScript, and other assets in parallel.
Use the wsgi.early_hints callback in your WSGI application:
Use the http.response.informational message type:
Early hints are only sent to HTTP/1.1+ clients. HTTP/1.0 clients silently ignore the callback since they don't support 1xx responses.
HTTP/2 allows clients to indicate the relative priority of streams using PRIORITY frames (RFC 7540 Section 5.3). Gunicorn tracks stream priorities and exposes them to both WSGI and ASGI applications.
Priority information is available in the WSGI environ for HTTP/2 requests:
For ASGI applications, priority is available in the scope's extensions dict:
Stream priority is advisory. Applications can use it for scheduling decisions, but Gunicorn does not enforce priority-based request ordering. Priority information is only present for HTTP/2 requests.
HTTP/2 supports trailing headers (trailers) sent after the response body. This is commonly used for gRPC status codes, checksums, and timing information.
For WSGI applications, use the gunicorn.http2.send_trailers callback in the environ:
For ASGI applications, use the http.response.trailers extension:
Configure nginx to proxy HTTP/2 connections to Gunicorn:
For nginx to forward 103 Early Hints from upstream, you need nginx 1.29+ and the early_hints directive.
For simpler deployments, Gunicorn can terminate TLS directly:
For production HTTP/2 deployments:
If clients fall back to HTTP/1.1:
If you see "HTTP/2 is not supported by the sync worker":
Increase flow control window sizes: