httpx Switch to explicit typing.Optional throughout (Fix)

The Fix

Upgrade to version 0.23.0 or later.

Based on closed encode/httpx issue #2092 · PR/commit linked

Production note: Most teams hit this during upgrades or environment changes. Roll out with a canary and smoke critical endpoints (health, OpenAPI/docs) before 100%.

Jump to Verify Open PR/Commit

@@ -24,19 +24,19 @@ def request(
     url: URLTypes,
     *,
-    params: QueryParamTypes = None,
-    content: RequestContent = None,
-    data: RequestData = None,

repro.py

from contextlib import AsyncExitStack

import httpx


async def main() -> None:
    async with AsyncExitStack() as stack:
        http_client = await stack.enter_async_context(httpx.AsyncClient())
        reveal_type(http_client)

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

fix.md

Option A — Upgrade to fixed release\nUpgrade to version 0.23.0 or later.\nWhen NOT to use: This fix should not be used if backward compatibility with previous type annotations is required.\n\n

Why This Fix Works in Production

Trigger: repro.py:8: error: Need type annotation for "http_client" [var-annotated]
Mechanism: Type annotations in httpx were not using Optional, causing mypy strict mode errors
Why the fix works: Switches to explicit typing.Optional throughout the codebase to resolve type issues with mypy in strict mode. (first fixed release: 0.23.0).

Production impact:

If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.

Why This Breaks in Prod

Type annotations in httpx were not using Optional, causing mypy strict mode errors
Production symptom (often without a traceback): repro.py:8: error: Need type annotation for "http_client" [var-annotated]

Proof / Evidence

GitHub issue: #2092
Fix PR: https://github.com/encode/httpx/pull/2096
First fixed release: 0.23.0
Reproduced locally: No (not executed)
Last verified: 2026-02-09
Confidence: 0.75
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.64

Verified Execution

We executed the runnable minimal repro in a temporary environment and captured exit codes + logs.

Status: PASS
Ran: 2026-02-11T16:52:29Z
Package: httpx
Fixed: 0.23.0
Mode: fixed_only
Outcome: ok

Logs

affected (exit=None)

fixed (exit=0)

Discussion

High-signal excerpts from the issue thread (symptoms, repros, edge-cases).

Jump to Sources Open on GitHub

“Hi @michaeloliverx, Yup, this seems correct and well scoped, I guess at this point a PR attempting to fix that type annotation to Optional and…”

@florimondmanca · 2022-02-26 · confirmation · source

“Perhaps we should re-title this as the more general case. Something like "Switch to explicit typing.Optional throughout" (?)”

@lovelydinosaur · 2022-02-28 · source

“See also https://github.com/encode/httpx/pull/1760, https://github.com/encode/httpx/discussions/1747”

@lovelydinosaur · 2022-02-28 · source

“If no one has picked this up yet, I'm happy to take a crack at it”

@nhoad · 2022-03-04 · source

Failure Signature (Search String)

repro.py:8: error: Need type annotation for "http_client" [var-annotated]
repro.py:8: error: Argument 1 to "enter_async_context" of "AsyncExitStack" has incompatible type "AsyncClient"; expected "AsyncContextManager[<nothing>]" [arg-type]

Copy-friendly signature

signature.txt

Failure Signature
-----------------
repro.py:8: error: Need type annotation for "http_client"  [var-annotated]
repro.py:8: error: Argument 1 to "enter_async_context" of "AsyncExitStack" has incompatible type "AsyncClient"; expected "AsyncContextManager[<nothing>]"  [arg-type]

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
repro.py:8: error: Need type annotation for "http_client"  [var-annotated]
repro.py:8: error: Argument 1 to "enter_async_context" of "AsyncExitStack" has incompatible type "AsyncClient"; expected "AsyncContextManager[<nothing>]"  [arg-type]

Minimal Reproduction

repro.py

from contextlib import AsyncExitStack

import httpx


async def main() -> None:
    async with AsyncExitStack() as stack:
        http_client = await stack.enter_async_context(httpx.AsyncClient())
        reveal_type(http_client)

What Broke

Users experienced type checking failures when using mypy in strict mode.

Why It Broke

Type annotations in httpx were not using Optional, causing mypy strict mode errors

Fix Options (Details)

Option A — Upgrade to fixed release Safe default (recommended)

Upgrade to version 0.23.0 or later.

When NOT to use: This fix should not be used if backward compatibility with previous type annotations is required.

Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.

Fix reference: https://github.com/encode/httpx/pull/2096

First fixed release: 0.23.0

Last verified: 2026-02-09. Validate in your environment.

When NOT to Use This Fix

This fix should not be used if backward compatibility with previous type annotations is required.

Verify Fix

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

Did This Fix Work in Your Case?

Quick signal helps us prioritize which fixes to verify and improve.

Prevention

Add a CI check that diffs key outputs after upgrades (OpenAPI schema snapshots, JSON payload shapes, CLI output).
Upgrade behind a canary and run integration tests against the canary before 100% rollout.

Version Compatibility Table

Version	Status
0.23.0	Fixed

Related Issues

No related fixes found.

Cluster: httpx:configuration-error All hubs All clusters

Related clusters: Data consistency Other Timeout

Sources

We don’t republish the full GitHub discussion text. Use the links above for context.