encode/httpx · error · ImportError

Using http2=True, but the 'h2' package is not installed. Mak

Error message

Using http2=True, but the 'h2' package is not installed. Make sure to install httpx using `pip install httpx[http2]`.

What it means

Raised as ImportError in the sync Client.__init__ when http2=True but 'import h2' fails. HTTP/2 support is an optional extra; httpx refuses to construct an HTTP/2-capable client without the h2 package installed.

Source

Thrown at httpx/_client.py:680

        super().__init__(
            auth=auth,
            params=params,
            headers=headers,
            cookies=cookies,
            timeout=timeout,
            follow_redirects=follow_redirects,
            max_redirects=max_redirects,
            event_hooks=event_hooks,
            base_url=base_url,
            trust_env=trust_env,
            default_encoding=default_encoding,
        )

        if http2:
            try:
                import h2  # noqa
            except ImportError:  # pragma: no cover
                raise ImportError(
                    "Using http2=True, but the 'h2' package is not installed. "
                    "Make sure to install httpx using `pip install httpx[http2]`."
                ) from None

        allow_env_proxies = trust_env and transport is None
        proxy_map = self._get_proxy_map(proxy, allow_env_proxies)

        self._transport = self._init_transport(
            verify=verify,
            cert=cert,
            trust_env=trust_env,
            http1=http1,
            http2=http2,
            limits=limits,
            transport=transport,
        )
        self._mounts: dict[URLPattern, BaseTransport | None] = {
            URLPattern(key): None

View on GitHub (pinned to b5addb64f0)

Solutions

1. Install the extra: pip install 'httpx[http2]'.
2. If HTTP/2 is not actually required, construct the client with http2=False (the default).
3. Pin both httpx and h2 (plus hyperframe, hpack) in requirements to keep them in sync.

Example fix

// before
httpx.Client(http2=True)  # ImportError
// after
# pip install 'httpx[http2]'
httpx.Client(http2=True)

import importlib.util, httpx
http2_available = importlib.util.find_spec("h2") is not None
if http2 and not http2_available:
    raise RuntimeError("http2=True requires h2; run: pip install 'httpx[http2]'")
client = httpx.Client(http2=http2 and http2_available)

import importlib.util

def http2_ready() -> bool:
    return importlib.util.find_spec("h2") is not None

try:
    client = httpx.Client(http2=True)
except ImportError:
    client = httpx.Client(http2=False)  # graceful fallback to HTTP/1.1

When it happens

Trigger: Constructing httpx.Client(http2=True) in an environment where the h2 distribution is not installed (plain 'pip install httpx' without extras).

Common situations: Forgot the [http2] extra in requirements; CI image with minimal httpx; Dockerfile installing bare httpx; upgrading/rebuilding env and dropping the extra.

Related errors

• Invalid "auth" argument: {auth!r}
• httpx.Timeout must either include a default, or set all four
• Unknown scheme for proxy URL {url!r}
• Using SOCKS proxy, but the 'socksio' package is not installe
• Proxy protocol must be either 'http', 'https', 'socks5', or

AI-assisted analysis of encode/httpx@b5addb64f0 (2026-08-04). Data as JSON: /data/errors/7a2e8b97126b590c.json. Report an issue: GitHub.