requests 2.34.1 mypy error: headers dict[str, str] has incompatible type

Requests ships type annotations, so its typing is part of its public API: a change can break type checking for downstream code even when the runtime behaviour is unchanged. In May 2026, psf/requests#7431 tightened the type of request headers from Mapping[str, str | bytes] to MutableMapping[str, str | bytes], so that code mutating Request.headers would type-check. It shipped in Requests 2.34.1 minutes after merge.

On 2026-10-07 we replayed the pull request through Warpway as it stood before merge. The Correctness lens reports that the new type rejects the most common way people pass headers: a plain dict[str, str]. The maintainers reached the same conclusion two hours after release, and 2.34.2 partially reverted it the next day.

The change

HeadersType: TypeAlias = MutableMapping[str, str | bytes] | None

How the bug works

Mapping is read-only, so it is covariant in its value type: a dict[str, str] is a valid Mapping[str, str | bytes], because reading a str where str | bytes is expected is always safe. MutableMapping allows writes, so it is invariant: a function that accepts MutableMapping[str, str | bytes] may store bytes into it, which would break a dictionary declared to hold only str. Type checkers therefore reject the call, even though Requests never writes to it and the code runs fine.

import requests

headers = {"Authorization": "Bearer token"}  # inferred as dict[str, str]
requests.get("https://example.com", headers=headers)

error: Argument "headers" to "get" has incompatible type "dict[str, str]";
expected "MutableMapping[str, str | bytes] | None"  [arg-type]

We reproduced this with mypy --strict on Requests 2.34.1. The same file passes on 2.34.0 and 2.34.2.

Are you affected?

Only if you run a type checker over code that uses Requests 2.34.1. Runtime behaviour did not change.

Fix or workaround

Upgrade to Requests 2.34.2, which moves the type back to Mapping. If you are pinned to 2.34.1, widen your annotation, which we verified passes:

headers: dict[str, str | bytes] = {"Authorization": "Bearer token"}