h2c support

[benoitc]

Bring H2C support to HTTP2 support.

Discussed in #3477

^{Originally posted by timkofu February 2, 2026}

Type

Feature Request

Description

HTTP/2 cleartext (h2c) is not supported due to security concerns and lack of browser support.

PaaS like fly.io and cloudrun support h2c, so we can have http2 features and the capabilities they unlock in our apps (without terminating TLS ourselves) and keep the advantages of their proxies.

Steps to Reproduce (for bugs)

No response

Configuration

No response

Logs / Error Output

No response

Gunicorn Version

gunicorn (version 25.0.0)

Python Version

Python 3.14.2

Worker Class

gthread

Operating System

Linux

Additional Context

No response

Checklist

• I have searched existing discussions and issues for duplicates
• I have checked the documentation and FAQ

[lewisdoesstuff]

Heya, this got marked as closed with a PR but i assume it referenced the wrong issue.

Is this still planned? While h2c might not be well supported by browsers, running gunicorn behind a reverse proxy/LB that terminates TLS means that requests must be downgraded to h11 upstream of it

[fluffy-dev]

Hey, I had a poke around the code to see how big a job h2c would actually be, and honestly it's smaller than I expected.

Right now HTTP/2 only kicks in over TLS via ALPN. If there's no TLS the code never even reaches the h2 path, and h2c is marked unsupported in the config docs. But the actual h2 connection is set up transport-agnostic (client_side=False), so it doesn't care whether the bytes come from TLS or plaintext. All the heavy stuff (streams, flow control, trailers, wsgi/asgi bridging) is already there. What's missing is just a way in over cleartext.

And the use case here isn't browsers, it's the Cloud Run / fly.io setup where the platform terminates TLS and talks h2c to your app. Without it that hop quietly drops to HTTP/1.1. For that you only need prior-knowledge h2c, where the client just opens plain TCP and sends the PRI * HTTP/2.0... preface straight away. The old Upgrade: h2c dance got dropped in RFC 9113 so I'd skip it.

So my thinking: add an opt-in flag (off by default), and in the h2-capable workers, when there's no TLS and the flag is on, peek the first 24 bytes for the preface and route into the existing handle_http2 path if it matches, otherwise fall back to HTTP/1.1 like normal. Documented as trusted-proxy only, which sidesteps the original security worry since that was really about Upgrade-style h2c and exposing cleartext h2 straight to the internet.

@benoitc since the docs say this is intentionally unsupported, it's your call whether to change that. If you're ok with the opt-in prior-knowledge approach I'm happy to take a crack at a PR, starting with the gthread worker.

[frittentheke]

@benoitc if you are looking for yet another use case:

We for example run Gunicorn containerized within an Istio Service Mesh.
In this context the traffic, including its encryption via mTLS, is being handled by a sidecar container.
Gunicorn is by no means exposed to the external client in this case.
But not being able to leverage the efficiency gains of HTTP/2 (due to the lack of h2c) between the sidecar and Gunicorn instance and thus falling back (down) to HTTP/1.1 connections and requests is really unfortunate.

@fluffy-dev would you maybe write up a PR with your proposed changes? Might make it even easier to judge the complexity (or lack thereof).

[fluffy-dev]

Wrote it up as a draft PR: #3663. Prior-knowledge only, opt-in --h2c flag, gthread worker, ~60 lines of code plus tests and docs. Flag off = zero behavior change. @frittentheke this covers the sidecar case - curl --http2-prior-knowledge against a plain port gets h2.