How to use HTTP/3 with cURL

Using HTTP/3 with curl enables testing modern, QUIC-based connections directly from the command line. Leveraging the latest protocol generation helps evaluate performance, latency behaviour, and resilience on paths where traditional HTTP/1.1 and HTTP/2 may suffer from head-of-line blocking or packet loss. Quick one-off requests make it easy to compare behaviour between protocol versions without changing browser settings or application code.

The curl client negotiates protocol versions with servers using ALPN and optional Alt-Svc hints, and can switch to HTTP/3 when both endpoints support QUIC. When built with libraries such as ngtcp2 and nghttp3, curl exposes --http3 and --http3-only flags to request the new transport while retaining the familiar syntax for headers, bodies, and authentication. Version output and transfer metadata reveal which protocol was used for each request, even when the connection silently falls back to HTTP/2 or HTTP/1.1.

Not every packaged build of curl includes QUIC support, and many servers still prefer earlier protocol versions or announce HTTP/3 only via DNS or Alt-Svc records. Firewalls and middleboxes can also block or rate-limit UDP traffic, which interrupts QUIC flows even when TCP-based HTTP remains functional. Forcing HTTP/3 exclusively can therefore produce errors on otherwise healthy endpoints, so output must be interpreted with awareness of these deployment constraints.

1. Open a terminal where curl is installed.

   $ whoami
   root

   Any shell with network access is sufficient as long as the curl binary resides in the PATH.

2. Check the compiled features in curl and confirm whether HTTP/3 support is present.

   $ curl -V
   curl 8.5.0 (aarch64-unknown-linux-gnu) libcurl/8.5.0 GnuTLS/3.8.3 brotli/1.1.0 zstd/1.5.5 libidn2/2.3.7 libpsl/0.21.2 (+libidn2/2.3.7) nghttp2/1.59.0 ngtcp2/1.20.0-DEV nghttp3/1.15.0-DEV
   Release-Date: 2023-12-06
   Protocols: dict file ftp ftps gopher gophers http https imap imaps mqtt pop3 pop3s rtsp smb smbs smtp smtps telnet tftp
   Features: alt-svc AsynchDNS brotli HSTS HTTP2 HTTP3 HTTPS-proxy IDN IPv6 Largefile NTLM PSL SSL threadsafe TLS-SRP UnixSockets zstd

   Absence of HTTP3 in the Features line indicates that the installed curl build cannot negotiate HTTP/3 until a QUIC-enabled build is used.

3. Attempt an HTTP/3 request to confirm that the installed curl build includes QUIC support.

   $ curl --http3 --head --silent --cacert /work/docker/certs/ca.crt "https://api.example.net/"
   HTTP/3 200 
   server: Caddy
   etag: "t8nd2h36"
   content-type: text/html; charset=utf-8
   last-modified: Sat, 10 Jan 2026 11:54:17 GMT
   accept-ranges: bytes
   content-length: 114
   date: Sat, 10 Jan 2026 11:58:39 GMT

   An error stating that --http3 is unsupported means a QUIC-capable curl build is required before HTTP/3 can be negotiated.

4. Force HTTP/3 only against a known QUIC-enabled endpoint and print just the negotiated protocol version.

   $ curl --http3-only --silent --output /dev/null --write-out "%{http_version}\n" --cacert /work/docker/certs/ca.crt "https://api.example.net/"
   3

   When --http3-only is used against a server or path that cannot complete a QUIC handshake, the transfer fails instead of falling back, which can resemble a generic connectivity issue even though earlier HTTP versions still work.

5. Inspect verbose logs while forcing HTTP/3 to verify that QUIC is used on the wire.

   $ curl --http3-only --silent --show-error --verbose --cacert /work/docker/certs/ca.crt "https://api.example.net/" --output /dev/null
   ##### snipped #####
   * using HTTP/3
   * [HTTP/3] [0] OPENED stream for https://api.example.net/
   * [HTTP/3] [0] [:method: GET]
   * [HTTP/3] [0] [:scheme: https]
   * [HTTP/3] [0] [:authority: api.example.net]
   * [HTTP/3] [0] [:path: /]
   * [HTTP/3] [0] [user-agent: curl/8.5.0]
   * [HTTP/3] [0] [accept: */*]
   > GET / HTTP/3
   > Host: api.example.net
   > User-Agent: curl/8.5.0
   > Accept: */*
   > 
   < HTTP/3 200 
   < date: Sat, 10 Jan 2026 11:58:39 GMT
   < server: Caddy
   < etag: "t8nd2h36"
   < content-type: text/html; charset=utf-8
   < last-modified: Sat, 10 Jan 2026 11:54:17 GMT
   < accept-ranges: bytes
   < content-length: 114
   < 
   ##### snipped #####

   Successful HTTP/3 usage is confirmed by the Features: HTTP3 flag in curl -V output, a value of 3 from %{http_version}, and verbose logs containing lines such as Using HTTP/3 with h3 pseudo-headers.