Update dependency urllib3 to v2 [SECURITY] - #14620

Details

Impact

urllib3 supports configuring TLS independently for an HTTPS proxy and the target server.

proxy_ssl_context, proxy_assert_hostname, and proxy_assert_fingerprint configure the TLS connection to the proxy. ssl_context and the other target-specific TLS parameters configure the connection to the target server.

In urllib3 versions 1.26.0 through 2.7.0, these configurations were not consistently separated. Depending on the proxy mode, urllib3 could:

1. Ignore proxy_ssl_context and use the target server's SSL context for the TLS connection to an HTTPS forwarding proxy.
2. Override the HTTPS proxy's certificate-verification policy with the target server's certificate-verification policy.
3. Apply target-specific SNI, hostname assertions, certificate fingerprint assertions, or TLS client credentials to the TLS connection to an HTTPS forwarding proxy.

In particular, configuring cert_reqs="CERT_NONE" for a target server could overwrite the verify_mode of the SSL context configured for the HTTPS proxy. This modification occurred in place and persisted on the context object, potentially disabling proxy certificate verification for later connections that reused the same context.

An attacker able to intercept the connection to an HTTPS proxy may be able to impersonate the proxy when the effective proxy TLS configuration disables certificate verification or otherwise accepts the attacker's certificate. This may occur, for example, when the target server's trust or identity policy is incorrectly applied to the proxy connection.

When HTTPS forwarding is enabled, an impersonated proxy can observe or modify forwarded requests and responses, potentially exposing credentials, authentication tokens, request bodies, response data, and other sensitive information.

A TLS client certificate intended for the target server may also be presented to the proxy or to an attacker impersonating it. This can disclose the client's identity and provide proof of possession of the corresponding private key. The private key itself is not transmitted during the TLS handshake.

In CONNECT tunneling mode, impersonating the HTTPS proxy does not by itself defeat the separate end-to-end TLS connection between the client and the target server.

Affected Usages

Code using urllib3 versions 1.26.0 through 2.7.0 may be affected in any of the following cases.

1. The target SSL context is used for an HTTPS forwarding proxy

HTTPS requests are forwarded through an HTTPS proxy with use_forwarding_for_https=True, and proxy_ssl_context is configured for the proxy.

urllib3 may ignore proxy_ssl_context and use the target server's ssl_context for the proxy TLS handshake. The proxy may therefore be verified using the target server's trust and certificate policy instead of the policy explicitly configured for the proxy.

2. The target verification policy overrides the proxy policy

An HTTPS proxy is configured with proxy_ssl_context, while the target server uses a different certificate-verification policy.

urllib3 may apply the target server's cert_reqs value to the proxy SSL context. For example, setting cert_reqs="CERT_NONE" for the target server may also disable certificate verification for the HTTPS proxy, even when proxy_ssl_context was configured to require verification.

This issue can affect the TLS connection to an HTTPS proxy in both forwarding and CONNECT tunneling configurations.

3. A mutated proxy SSL context is reused

The same SSL context is reused as proxy_ssl_context across multiple connections, and certificate verification is disabled for one target server.

urllib3 may modify the proxy SSL context's verify_mode in place. Later connections that reuse the same context may therefore connect to the HTTPS proxy without certificate verification.

4. Target-specific TLS identity or credentials are applied to the proxy

HTTPS requests are forwarded through an HTTPS proxy with use_forwarding_for_https=True, and target-specific SNI, hostname assertions, certificate fingerprint assertions, or TLS client credentials are configured.

urllib3 may apply these target-specific settings to the proxy TLS handshake. This may cause urllib3 to:

• send SNI intended for the target server to the proxy;
• verify the proxy using a hostname or certificate fingerprint intended for the target server; or
• present a TLS client certificate intended for the target server to the proxy.

Code connecting through a plain HTTP proxy does not establish a TLS connection to the proxy and is not affected by this issue.

Remediation

Upgrade to urllib3 2.8.0 or later.

urllib3 2.8.0 independently applies the explicitly configured proxy_ssl_context and proxy-specific certificate assertions to the HTTPS proxy connection. Target-specific SNI, certificate assertions, and TLS client certificate parameters are no longer applied to the HTTPS proxy handshake.

For backward compatibility, when an HTTPS proxy is used with use_forwarding_for_https=True and proxy_ssl_context is not provided, urllib3 2.8.0 continues to use ssl_context for the TLS connection to the proxy. This configuration emits a FutureWarning. In urllib3 3.0, passing ssl_context with use_forwarding_for_https=True for an HTTPS proxy will raise an error. Applications should use proxy_ssl_context to configure TLS for an HTTPS forwarding proxy.

The fixes were implemented in commits b6447295fff7b38fdffc67e0df9712d60cef3cc3 and 07408cec79d1856d81bb42c74a904a24fdb9e465.

Severity

• CVSS Score: 7.6 / 10 (High)
• Vector String: CVSS:4.0/AV:N/AC:L/AT:P/PR:N/UI:P/VC:H/VI:H/VA:N/SC:N/SI:N/SA:N

References

• https://github.com/urllib3/urllib3/security/advisories/GHSA-8988-9cw3-xx77
• https://nvd.nist.gov/vuln/detail/CVE-2026-97687
• https://github.com/urllib3/urllib3/pull/5093
• https://github.com/urllib3/urllib3/commit/07408cec79d1856d81bb42c74a904a24fdb9e465
• https://github.com/urllib3/urllib3/commit/b6447295fff7b38fdffc67e0df9712d60cef3cc3
• https://github.com/urllib3/urllib3/releases/tag/2.8.0
• https://github.com/advisories/GHSA-8988-9cw3-xx77

This data is provided by the GitHub Advisory Database (CC-BY 4.0).

Details

Impact

urllib3's streaming API is designed for efficiently handling large HTTP responses by reading the content in chunks, rather than loading the entire response body into memory at once. When decoding a chunked-transfer-encoded response, this API reads each chunk's size field by buffering until it sees \n or EOF.

A malicious HTTP server can return Transfer-Encoding: chunked and then send a very long run of bytes without any newline, causing the streaming client to buffer that entire run before urllib3 can reject the chunk size as invalid and allocate more memory than intended.

To fix the issue, we'll reject chunk-size fields larger than 65536 bytes, as already done in the non-streaming case, which is currently handled by the Python standard library. Note that this only applies to reading the chunk-size field, not the chunk data, which is already handled correctly. Thus, there shouldn't be any impact for non-malicious servers.

Affected usages

Applications and libraries using urllib3 versions earlier than 2.8.0 may be affected when streaming a chunked response from untrusted sources. Specifically, this affects the read_chunked() and stream() methods of the HTTPResponse object.

This also affects requests streaming API, which uses urllib3 under the hood.

Remediation

Upgrade to urllib3 version 2.8.0 or later, where chunk-size fields larger than 65536 will be rejected. If upgrading is not immediately possible, consider reading the response at once using the read() method.

Severity

• CVSS Score: 8.9 / 10 (High)
• Vector String: CVSS:4.0/AV:N/AC:L/AT:P/PR:N/UI:N/VC:N/VI:N/VA:H/SC:N/SI:N/SA:H

References

• https://github.com/urllib3/urllib3/security/advisories/GHSA-vxq7-64xx-v4gw
• https://nvd.nist.gov/vuln/detail/CVE-2026-97689
• https://github.com/urllib3/urllib3/commit/cd770b059b543be29298ea5c52afb0b1b090f5ed
• https://github.com/urllib3/urllib3/releases/tag/2.8.0
• https://github.com/advisories/GHSA-vxq7-64xx-v4gw

This data is provided by the GitHub Advisory Database (CC-BY 4.0).

Details

Impact

urllib3's streaming API is designed for the efficient handling of large HTTP responses by reading content in chunks instead of loading the entire response body into memory at once.

urllib3 can decompress response bodies according to the HTTP Content-Encoding header. When streaming a compressed, chunked response, urllib3 first consumes data already buffered by the decoder before reading the next HTTP chunk.

However, urllib3 versions from 2.6.2 through 2.7.0 could enter an infinite loop when a chunked response contained bytes after the end of the Deflate stream. If the decompressed body exceeded the requested streaming chunk size, Python's zlib implementation could retain the trailing bytes as unconsumed input after reaching the end of the compressed stream. urllib3 would repeatedly attempt to decode those same bytes without making progress or reading more data from the network.

A malicious server could exploit this behavior to cause excessive CPU usage and prevent the affected request from completing on the client. Network read timeouts would not interrupt the loop because no further socket operation was required.

Affected usages

Applications and libraries using urllib3 versions 2.6.2 through 2.7.0 may be affected when all of the following conditions are met:

1. Compressed responses from an untrusted source are streamed using HTTPResponse.stream(amt=N) or HTTPResponse.read_chunked(amt=N) with a positive, finite chunk size.
2. Content decoding is enabled.
3. The response uses both Transfer-Encoding: chunked and Content-Encoding: deflate.
4. The decoded body exceeds the requested chunk size and the encoded body contains bytes after the end of the Deflate stream.

HTTPResponse.stream() uses a finite chunk size by default and is therefore affected when the other conditions are met.

Remediation

Upgrade to urllib3 2.8.0, in which the Deflate decoder stops accepting input after reaching the end of the compressed stream and no longer reports trailing bytes as data that can produce more decoded output.

If upgrading is not immediately possible, disable automatic content decoding for responses from untrusted sources by setting decode_content=False, or reject streamed responses using the Deflate content encoding. Applications that disable automatic decoding must handle the compressed response safely at another layer.

Severity

• CVSS Score: 6.9 / 10 (Medium)
• Vector String: CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:N/VI:N/VA:L/SC:N/SI:N/SA:N

References

• https://github.com/urllib3/urllib3/security/advisories/GHSA-gh4c-6fx4-qh6g
• https://nvd.nist.gov/vuln/detail/CVE-2026-97688
• https://github.com/urllib3/urllib3/commit/ea2ad7b21a80da3632f80016526a18864586077f
• https://github.com/urllib3/urllib3/releases/tag/2.8.0
• https://github.com/advisories/GHSA-gh4c-6fx4-qh6g

This data is provided by the GitHub Advisory Database (CC-BY 4.0).

v2.8.0

Compare Source

==================

Security

Fixed the following security issues:

• The TLS configuration for HTTPS proxies could be ignored or overridden.
  (High severity, GHSA-8988-9cw3-xx77 <https://github.com/urllib3/urllib3/security/advisories/GHSA-8988-9cw3-xx77>__)
• HTTPResponse.stream() and read_chunked() could buffer a chunk-size
  line of unbounded length in memory. (High severity,
  GHSA-vxq7-64xx-v4gw <https://github.com/urllib3/urllib3/security/advisories/GHSA-vxq7-64xx-v4gw>__)
• Chunked Deflate streaming could enter an infinite loop. (Medium severity,
  GHSA-gh4c-6fx4-qh6g <https://github.com/urllib3/urllib3/security/advisories/GHSA-gh4c-6fx4-qh6g>__)

.. caution::

urllib3 2.8.0 fixes HTTPS proxy TLS configuration being ignored or
overridden by destination settings. Configurations relying on that
behavior may require changes.

Configure proxy CA certificates and client certificates in
``proxy_ssl_context``, and proxy identity checks with
``proxy_assert_hostname`` or ``proxy_assert_fingerprint``.
Destination client certificates and identity overrides no longer
apply to HTTPS forwarding proxy connections.

Deprecations & Removals

• Deprecated using an empty collection as the Retry option
  allowed_methods to retry any verb.
  (#&#8203;5044 <https://github.com/urllib3/urllib3/issues/5044>__)

Features

• Added Url.auth_decoded and Url.auth_decoded_joined convenience
  properties to the result of parse_url().
  (#&#8203;4945 <https://github.com/urllib3/urllib3/issues/4945>__)
• Added basic_auth_encoding and proxy_basic_auth_encoding parameters to
  urllib3.util.make_headers().
  (#&#8203;5092 <https://github.com/urllib3/urllib3/issues/5092>__)

Bugfixes

• Fixed response header handling to replace obsolete folded header lines
  (obs-fold) with spaces in accordance with RFC 9112, preventing raw CRLF
  sequences from appearing in header values such as Set-Cookie.
  (#&#8203;1362 <https://github.com/urllib3/urllib3/issues/1362>__)

• Fixed usage of proxy_ssl_context with ProxyManager when
  use_forwarding_for_https=True. Passing ssl_context instead of
  proxy_ssl_context for HTTPS proxies in this configuration now emits a
  FutureWarning and will raise an error in v3.0.
  (#&#8203;2577 <https://github.com/urllib3/urllib3/issues/2577>__)

• Changed behavior of the default ConnectionPool.pool initialization.
  LifoQueue is now resolved from the queue module after the
  ConnectionPool is instantiated instead of using the default cached
  QueueCls class property. This is done because sometimes the
  queue.LifoQueue is monkey-patched late in the program, such as by gevent.
  (#&#8203;3289 <https://github.com/urllib3/urllib3/issues/3289>__)

• Raised UnrewindableBodyError instead of ValueError when retrying a
  request whose body had tell() but not seek().
  (#&#8203;3779 <https://github.com/urllib3/urllib3/issues/3779>__)

• Decoded percent-encoded SOCKS proxy credentials before authenticating with
  the proxy server.
  (#&#8203;3785 <https://github.com/urllib3/urllib3/issues/3785>__)

• Fixed HTTPResponse.drain_conn() to discard unread response data in 64 KiB
  chunks (same as the default amt when doing HTTPResponse.stream(...)).
  (#&#8203;5019 <https://github.com/urllib3/urllib3/issues/5019>__)

• Fixed is_ipaddress() to detect non-standard IPv4 forms accepted by
  socket.connect, such as hex (0x7f000001), octal (0177.0.0.1), and
  decimal integers (2130706433), ensuring SSL certificate verification uses
  the correct mode for these addresses.
  (#&#8203;5029 <https://github.com/urllib3/urllib3/issues/5029>__)

• Fixed HTTPConnectionPool.urlopen raising a misleading FullPoolError
  instead of ValueError when called with an invalid timeout argument on
  a pool created with block=True.
  (#&#8203;5059 <https://github.com/urllib3/urllib3/issues/5059>__)

• Fixed port-zero handling to preserve explicit :0 values instead of
  substituting the default ports 80 or 443 in URL parsing, pool selection,
  proxy configuration, connection_from_url(), and HTTP/2 request authority.
  (#&#8203;5071 <https://github.com/urllib3/urllib3/issues/5071>,
  #&#8203;5101 <https://github.com/urllib3/urllib3/issues/5101>)

• Fixed a bug where PoolManager passed the assert_hostname and
  assert_fingerprint parameters to HTTP connection pools.
  (#&#8203;5077 <https://github.com/urllib3/urllib3/issues/5077>__)

• Fixed HTTPConnectionPool.urlopen() and HTTP proxy forwarding to strip URL
  fragments from absolute request targets before sending requests.
  (#&#8203;5079 <https://github.com/urllib3/urllib3/issues/5079>__)

• Added safeguards to the proxy tunneling code to prevent potential security
  issues when handling invalid characters in the proxy host and HTTP headers.
  This change affects users of Python 3.10, Python 3.11, and Python 3.12 when
  the standard library does not contain the fix; those on newer Python versions
  should upgrade to 3.13.14+ or 3.14.5+ to get the same security fixes.
  (#&#8203;5091 <https://github.com/urllib3/urllib3/issues/5091>__)

• Fixed HTTPSConnection.connect() overriding ProxyConfig.ssl_context's
  certificate policy and proxy identity checks with the target connection's TLS
  settings when forwarding through an HTTPS proxy.

  HTTPSConnection no longer applies target SNI, assertions, or client
  credentials to forwarding proxy handshakes and continues to use its
  ssl_context as a fallback when an HTTPS proxy forwards an HTTP target.
  (#&#8203;5093 <https://github.com/urllib3/urllib3/issues/5093>__)

• Fixed URL parsing to more strictly enforce RFC 3986 host syntax, rejecting
  invalid host input such as raw spaces and control characters, malformed
  percent-encodings, and percent-encoded control characters in HTTP(S) hosts
  and IPv6 zone identifiers, including proxy CONNECT tunnel targets. Host
  normalization now also follows RFC 3986 normalization rules for
  percent-encoded octets by decoding percent-encoded unreserved characters and
  uppercasing the hexadecimal digits of retained percent-encoded octets.
  (#&#8203;5095 <https://github.com/urllib3/urllib3/issues/5095>__)

• Fixed an AttributeError on Python built with OpenSSL 4+, where
  ssl.PROTOCOL_TLSv1 no longer exists.
  (#&#8203;5097 <https://github.com/urllib3/urllib3/issues/5097>__)

• Fixed urllib3.contrib.pyopenssl to use cryptography APIs when reading a
  certificate subject and loading encrypted private keys, avoiding
  DeprecationWarning raised by pyOpenSSL 26.3.0+.
  (#&#8203;5103 <https://github.com/urllib3/urllib3/issues/5103>__)

• Fixed handling of HTTP 303 redirects for requests with chunked or file-like
  bodies.
  (#&#8203;5161 <https://github.com/urllib3/urllib3/issues/5161>__)

• Fixed assert_fingerprint() to raise SSLError instead of
  binascii.Error when a fingerprint has a supported length but contains
  non-hexadecimal characters.
  (#&#8203;5211 <https://github.com/urllib3/urllib3/issues/5211>__)

Misc

• Added a test dependency group containing the minimum dependencies needed
  to run the test suite, intended for downstream packagers. The dev-base
  and mypy groups now include this new group via include-group,
  removing duplication.
  (#&#8203;3594 <https://github.com/urllib3/urllib3/issues/3594>__)
• Fixed test failures with pytest >= 9.1.
  (#&#8203;5094 <https://github.com/urllib3/urllib3/issues/5094>__)
• Enabled JSPI tests with Firefox in the Emscripten test suite.
  (#&#8203;5166 <https://github.com/urllib3/urllib3/issues/5166>__)
• Improved streamed response decoding performance.
  (#&#8203;5209 <https://github.com/urllib3/urllib3/issues/5209>__)
• Fixed flaky tests.
  (#&#8203;5232 <https://github.com/urllib3/urllib3/issues/5232>,
  #&#8203;5234 <https://github.com/urllib3/urllib3/issues/5234>,
  #&#8203;5239 <https://github.com/urllib3/urllib3/issues/5239>__)

v2.7.0

Compare Source

=======================

Security

Addressed high-severity security issues.
Impact was limited to specific use cases detailed in the accompanying
advisories; overall user exposure was estimated to be marginal.

• Decompression-bomb safeguards of the streaming API were bypassed:

  1. When HTTPResponse.drain_conn() was called after the response had been
     read and decompressed partially.
  2. During the second HTTPResponse.read(amt=N) or
     HTTPResponse.stream(amt=N) call when the response was decompressed
     using the official Brotli <https://pypi.org/project/brotli/>__ library.

  See GHSA-mf9v-mfxr-j63j <https://github.com/urllib3/urllib3/security/advisories/GHSA-mf9v-mfxr-j63j>__
  for details.

• HTTP pools created using ProxyManager.connection_from_url did not strip
  sensitive headers specified in Retry.remove_headers_on_redirect when
  redirecting to a different host.
  (GHSA-qccp-gfcp-xxvc <https://github.com/urllib3/urllib3/security/advisories/GHSA-qccp-gfcp-xxvc>__)

Deprecations and Removals

• Used FutureWarning instead of DeprecationWarning for better
  visibility of existing deprecation notices. Rescheduled the removal of
  deprecated features to version 3.0.
  (#&#8203;3763 <https://github.com/urllib3/urllib3/issues/3763>__)
• Removed support for end-of-life Python 3.9.
  (#&#8203;3720 <https://github.com/urllib3/urllib3/issues/3720>__)
• Removed support for end-of-life PyPy3.10.
  (#&#8203;4979 <https://github.com/urllib3/urllib3/issues/4979>__)
• Bumped the minimum supported pyOpenSSL version to 19.0.0.
  (#&#8203;3777 <https://github.com/urllib3/urllib3/issues/3777>__)

Bugfixes

• Fixed a bug where HTTPResponse.read(amt=None) was ignoring decompressed
  data buffered from previous partial reads.
  (#&#8203;3636 <https://github.com/urllib3/urllib3/issues/3636>__)
• Fixed a bug where HTTPResponse.read() could cache only part of the
  response after a partial read when cache_content=True.
  (#&#8203;4967 <https://github.com/urllib3/urllib3/issues/4967>__)
• Fixed HTTPResponse.stream() and HTTPResponse.read_chunked() to handle
  amt=0.
  (#&#8203;3793 <https://github.com/urllib3/urllib3/issues/3793>__)
• Updated _TYPE_BODY type alias to include missing Iterable[str],
  matching the documented and runtime behavior of chunked request bodies.
  (#&#8203;3798 <https://github.com/urllib3/urllib3/issues/3798>__)
• Fixed LocationParseError when paths resembling schemeless URIs were
  passed to HTTPConnectionPool.urlopen().
  (#&#8203;3352 <https://github.com/urllib3/urllib3/issues/3352>__)
• Fixed BaseHTTPResponse.readinto() type annotation to accept
  memoryview in addition to bytearray, matching the
  io.RawIOBase.readinto contract and enabling use with
  io.BufferedReader without type errors.
  (#&#8203;3764 <https://github.com/urllib3/urllib3/issues/3764>__)

v2.6.3

Compare Source

==================

• Fixed a high-severity security issue where decompression-bomb safeguards of
  the streaming API were bypassed when HTTP redirects were followed.
  (GHSA-38jv-5279-wg99 <https://github.com/urllib3/urllib3/security/advisories/GHSA-38jv-5279-wg99>__)
• Started treating Retry-After times greater than 6 hours as 6 hours by
  default. (#&#8203;3743 <https://github.com/urllib3/urllib3/issues/3743>__)
• Fixed urllib3.connection.VerifiedHTTPSConnection on Emscripten.
  (#&#8203;3752 <https://github.com/urllib3/urllib3/issues/3752>__)

v2.6.2

Compare Source

==================

• Fixed HTTPResponse.read_chunked() to properly handle leftover data in
  the decoder's buffer when reading compressed chunked responses.
  (#&#8203;3734 <https://github.com/urllib3/urllib3/issues/3734>__)

v2.6.1

Compare Source

==================

• Restore previously removed HTTPResponse.getheaders() and
  HTTPResponse.getheader() methods.
  (#&#8203;3731 <https://github.com/urllib3/urllib3/issues/3731>__)

v2.6.0

Compare Source

==================

Security

• Fixed a security issue where streaming API could improperly handle highly
  compressed HTTP content ("decompression bombs") leading to excessive resource
  consumption even when a small amount of data was requested. Reading small
  chunks of compressed data is safer and much more efficient now.
  (GHSA-2xpw-w6gg-jr37 <https://github.com/urllib3/urllib3/security/advisories/GHSA-2xpw-w6gg-jr37>__)
• Fixed a security issue where an attacker could compose an HTTP response with
  virtually unlimited links in the Content-Encoding header, potentially
  leading to a denial of service (DoS) attack by exhausting system resources
  during decoding. The number of allowed chained encodings is now limited to 5.
  (GHSA-gm62-xv2j-4w53 <https://github.com/urllib3/urllib3/security/advisories/GHSA-gm62-xv2j-4w53>__)

.. caution::

• If urllib3 is not installed with the optional urllib3[brotli] extra, but
  your environment contains a Brotli/brotlicffi/brotlipy package anyway, make
  sure to upgrade it to at least Brotli 1.2.0 or brotlicffi 1.2.0.0 to
  benefit from the security fixes and avoid warnings. Prefer using
  urllib3[brotli] to install a compatible Brotli package automatically.

• If you use custom decompressors, please make sure to update them to
  respect the changed API of urllib3.response.ContentDecoder.

Features

• Enabled retrieval, deletion, and membership testing in HTTPHeaderDict using bytes keys. (#&#8203;3653 <https://github.com/urllib3/urllib3/issues/3653>__)
• Added host and port information to string representations of HTTPConnection. (#&#8203;3666 <https://github.com/urllib3/urllib3/issues/3666>__)
• Added support for Python 3.14 free-threading builds explicitly. (#&#8203;3696 <https://github.com/urllib3/urllib3/issues/3696>__)

Removals

• Removed the HTTPResponse.getheaders() method in favor of HTTPResponse.headers.
  Removed the HTTPResponse.getheader(name, default) method in favor of HTTPResponse.headers.get(name, default). (#&#8203;3622 <https://github.com/urllib3/urllib3/issues/3622>__)

Bugfixes

• Fixed redirect handling in urllib3.PoolManager when an integer is passed
  for the retries parameter. (#&#8203;3649 <https://github.com/urllib3/urllib3/issues/3649>__)
• Fixed HTTPConnectionPool when used in Emscripten with no explicit port. (#&#8203;3664 <https://github.com/urllib3/urllib3/issues/3664>__)
• Fixed handling of SSLKEYLOGFILE with expandable variables. (#&#8203;3700 <https://github.com/urllib3/urllib3/issues/3700>__)

Misc

• Changed the zstd extra to install backports.zstd instead of zstandard on Python 3.13 and before. (#&#8203;3693 <https://github.com/urllib3/urllib3/issues/3693>__)
• Improved the performance of content decoding by optimizing BytesQueueBuffer class. (#&#8203;3710 <https://github.com/urllib3/urllib3/issues/3710>__)
• Allowed building the urllib3 package with newer setuptools-scm v9.x. (#&#8203;3652 <https://github.com/urllib3/urllib3/issues/3652>__)
• Ensured successful urllib3 builds by setting Hatchling requirement to >= 1.27.0. (#&#8203;3638 <https://github.com/urllib3/urllib3/issues/3638>__)

v2.5.0

Compare Source

==================

Features

• Added support for the compression.zstd module that is new in Python 3.14.
  See PEP 784 <https://peps.python.org/pep-0784/>_ for more information. (#&#8203;3610 <https://github.com/urllib3/urllib3/issues/3610>__)
• Added support for version 0.5 of hatch-vcs (#&#8203;3612 <https://github.com/urllib3/urllib3/issues/3612>__)

Bugfixes

• Fixed a security issue where restricting the maximum number of followed
  redirects at the urllib3.PoolManager level via the retries parameter
  did not work.
• Made the Node.js runtime respect redirect parameters such as retries
  and redirects.
• Raised exception for HTTPResponse.shutdown on a connection already released to the pool. (#&#8203;3581 <https://github.com/urllib3/urllib3/issues/3581>__)
• Fixed incorrect CONNECT statement when using an IPv6 proxy with connection_from_host. Previously would not be wrapped in []. (#&#8203;3615 <https://github.com/urllib3/urllib3/issues/3615>__)

v2.4.0

Compare Source

==================

Features

• Applied PEP 639 by specifying the license fields in pyproject.toml. (#&#8203;3522 <https://github.com/urllib3/urllib3/issues/3522>__)
• Updated exceptions to save and restore more properties during the pickle/serialization process. (#&#8203;3567 <https://github.com/urllib3/urllib3/issues/3567>__)
• Added verify_flags option to create_urllib3_context with a default of VERIFY_X509_PARTIAL_CHAIN and VERIFY_X509_STRICT for Python 3.13+. (#&#8203;3571 <https://github.com/urllib3/urllib3/issues/3571>__)

Bugfixes

• Fixed a bug with partial reads of streaming data in Emscripten. (#&#8203;3555 <https://github.com/urllib3/urllib3/issues/3555>__)

Misc

• Switched to uv for installing development dependecies. (#&#8203;3550 <https://github.com/urllib3/urllib3/issues/3550>__)
• Removed the multiple.intoto.jsonl asset from GitHub releases. Attestation of release files since v2.3.0 can be found on PyPI. (#&#8203;3566 <https://github.com/urllib3/urllib3/issues/3566>__)

v2.3.0

Compare Source

==================

Features

• Applied PEP 639 by specifying the license fields in pyproject.toml. (#&#8203;3522 <https://github.com/urllib3/urllib3/issues/3522>__)
• Updated exceptions to save and restore more properties during the pickle/serialization process. (#&#8203;3567 <https://github.com/urllib3/urllib3/issues/3567>__)
• Added verify_flags option to create_urllib3_context with a default of VERIFY_X509_PARTIAL_CHAIN and VERIFY_X509_STRICT for Python 3.13+. (#&#8203;3571 <https://github.com/urllib3/urllib3/issues/3571>__)

Bugfixes

• Fixed a bug with partial reads of streaming data in Emscripten. (#&#8203;3555 <https://github.com/urllib3/urllib3/issues/3555>__)

Misc

• Switched to uv for installing development dependecies. (#&#8203;3550 <https://github.com/urllib3/urllib3/issues/3550>__)
• Removed the multiple.intoto.jsonl asset from GitHub releases. Attestation of release files since v2.3.0 can be found on PyPI. (#&#8203;3566 <https://github.com/urllib3/urllib3/issues/3566>__)

v2.2.3

Compare Source

==================

Features

• Added support for Python 3.13. (#&#8203;3473 <https://github.com/urllib3/urllib3/issues/3473>__)

Bugfixes

• Fixed the default encoding of chunked request bodies to be UTF-8 instead of ISO-8859-1.
  All other methods of supplying a request body already use UTF-8 starting in urllib3 v2.0. (#&#8203;3053 <https://github.com/urllib3/urllib3/issues/3053>__)
• Fixed ResourceWarning on CONNECT with Python < 3.11.4 by backporting python/cpython#103472. (#&#8203;3252 <https://github.com/urllib3/urllib3/issues/3252>__)
• Adjust tolerance for floating-point comparison on Windows to avoid flakiness in CI (#&#8203;3413 <https://github.com/urllib3/urllib3/issues/3413>__)
• Fixed a crash where certain standard library hash functions were absent in restricted environments. (#&#8203;3432 <https://github.com/urllib3/urllib3/issues/3432>__)
• Fixed mypy error when adding to HTTPConnection.default_socket_options. (#&#8203;3448 <https://github.com/urllib3/urllib3/issues/3448>__)

HTTP/2 (experimental)

HTTP/2 support is still in early development.

• Excluded Transfer-Encoding: chunked from HTTP/2 request body (#&#8203;3425 <https://github.com/urllib3/urllib3/issues/3425>__)

• Added version checking for h2 (https://pypi.org/project/h2/) usage.

  Now only accepting supported h2 major version 4.x.x. (#&#8203;3290 <https://github.com/urllib3/urllib3/issues/3290>__)

• Added a probing mechanism for determining whether a given target origin
  supports HTTP/2 via ALPN. (#&#8203;3301 <https://github.com/urllib3/urllib3/issues/3301>__)

• Add support for sending a request body with HTTP/2 (#&#8203;3302 <https://github.com/urllib3/urllib3/issues/3302>__)

Deprecations and Removals

• Note for downstream distributors: the _version.py file has been removed and is now created at build time by hatch-vcs. (#&#8203;3412 <https://github.com/urllib3/urllib3/issues/3412>__)
• Drop support for end-of-life PyPy3.8 and PyPy3.9. (#&#8203;3475 <https://github.com/urllib3/urllib3/issues/3475>__)

v2.2.2

Compare Source

==================

• Added the Proxy-Authorization header to the list of headers to strip from requests when redirecting to a different host. As before, different headers can be set via Retry.remove_headers_on_redirect.
• Allowed passing negative integers as amt to read methods of http.client.HTTPResponse as an alternative to None. (#&#8203;3122 <https://github.com/urllib3/urllib3/issues/3122>__)
• Fixed return types representing copying actions to use typing.Self. (#&#8203;3363 <https://github.com/urllib3/urllib3/issues/3363>__)

v2.2.1

Compare Source

==================

• Fixed issue where InsecureRequestWarning was emitted for HTTPS connections when using Emscripten. (#&#8203;3331 <https://github.com/urllib3/urllib3/issues/3331>__)
• Fixed HTTPConnectionPool.urlopen to stop automatically casting non-proxy headers to HTTPHeaderDict. This change was premature as it did not apply to proxy headers and HTTPHeaderDict does not handle byte header values correctly yet. (#&#8203;3343 <https://github.com/urllib3/urllib3/issues/3343>__)
• Changed InvalidChunkLength to ProtocolError when response terminates before the chunk length is sent. (#&#8203;2860 <https://github.com/urllib3/urllib3/issues/2860>__)
• Changed ProtocolError to be more verbose on incomplete reads with excess content. (#&#8203;3261 <https://github.com/urllib3/urllib3/issues/3261>__)

v2.2.0

Compare Source

==================

• Added support for Emscripten and Pyodide <https://urllib3.readthedocs.io/en/latest/reference/contrib/emscripten.html>, including streaming support in cross-origin isolated browser environments where threading is enabled. (#&#8203;2951 <https://github.com/urllib3/urllib3/issues/2951>)
• Added support for HTTPResponse.read1() method. (#&#8203;3186 <https://github.com/urllib3/urllib3/issues/3186>__)
• Added rudimentary support for HTTP/2. (#&#8203;3284 <https://github.com/urllib3/urllib3/issues/3284>__)
• Fixed issue where requests against urls with trailing dots were failing due to SSL errors
  when using proxy. (#&#8203;2244 <https://github.com/urllib3/urllib3/issues/2244>__)
• Fixed HTTPConnection.proxy_is_verified and HTTPSConnection.proxy_is_verified
  to be always set to a boolean after connecting to a proxy. It could be
  None in some cases previously. (#&#8203;3130 <https://github.com/urllib3/urllib3/issues/3130>__)
• Fixed an issue where headers passed in a request with json= would be mutated (#&#8203;3203 <https://github.com/urllib3/urllib3/issues/3203>__)
• Fixed HTTPSConnection.is_verified to be set to False when connecting
  from a HTTPS proxy to an HTTP target. It was set to True previously. (#&#8203;3267 <https://github.com/urllib3/urllib3/issues/3267>__)
• Fixed handling of new error message from OpenSSL 3.2.0 when configuring an HTTP proxy as HTTPS (#&#8203;3268 <https://github.com/urllib3/urllib3/issues/3268>__)
• Fixed TLS 1.3 post-handshake auth when the server certificate validation is disabled (#&#8203;3325 <https://github.com/urllib3/urllib3/issues/3325>__)
• Note for downstream distributors: To run integration tests, you now need to run the tests a second
  time with the --integration pytest flag. (#&#8203;3181 <https://github.com/urllib3/urllib3/issues/3181>__)

v2.1.0

Compare Source

==================

• Removed support for the deprecated urllib3[secure] extra. (#&#8203;2680 <https://github.com/urllib3/urllib3/issues/2680>__)
• Removed support for the deprecated SecureTransport TLS implementation. (#&#8203;2681 <https://github.com/urllib3/urllib3/issues/2681>__)
• Removed support for the end-of-life Python 3.7. (#&#8203;3143 <https://github.com/urllib3/urllib3/issues/3143>__)
• Allowed loading CA certificates from memory for proxies. (#&#8203;3065 <https://github.com/urllib3/urllib3/issues/3065>__)
• Fixed decoding Gzip-encoded responses which specified x-gzip content-encoding. (#&#8203;3174 <https://github.com/urllib3/urllib3/issues/3174>__)

v2.0.7

Compare Source

==================

• Made body stripped from HTTP requests changing the request method to GET after HTTP 303 "See Other" redirect responses.

v2.0.6

Compare Source

==================

• Added the Cookie header to the list of headers to strip from requests when redirecting to a different host. As before, different headers can be set via Retry.remove_headers_on_redirect.

v2.0.5

Compare Source

==================

• Allowed pyOpenSSL third-party module without any deprecation warning. (#&#8203;3126 <https://github.com/urllib3/urllib3/issues/3126>__)
• Fixed default blocksize of HTTPConnection classes to match high-level classes. Previously was 8KiB, now 16KiB. (#&#8203;3066 <https://github.com/urllib3/urllib3/issues/3066>__)

v2.0.4

Compare Source

==================

• Added support for union operators to HTTPHeaderDict (#&#8203;2254 <https://github.com/urllib3/urllib3/issues/2254>__)
• Added BaseHTTPResponse to urllib3.__all__ (#&#8203;3078 <https://github.com/urllib3/urllib3/issues/3078>__)
• Fixed urllib3.connection.HTTPConnection to raise the http.client.connect audit event to have the same behavior as the standard library HTTP client (#&#8203;2757 <https://github.com/urllib3/urllib3/issues/2757>__)
• Relied on the standard library for checking hostnames in supported PyPy releases (#&#8203;3087 <https://github.com/urllib3/urllib3/issues/3087>__)

v2.0.3

Compare Source

==================

• Allowed alternative SSL libraries such as LibreSSL, while still issuing a warning as we cannot help users facing issues with implementations other than OpenSSL. (#&#8203;3020 <https://github.com/urllib3/urllib3/issues/3020>__)
• Deprecated URLs which don't have an explicit scheme (#&#8203;2950 <https://github.com/urllib3/urllib3/pull/2950>_)
• Fixed response decoding with Zstandard when compressed data is made of several frames. (#&#8203;3008 <https://github.com/urllib3/urllib3/issues/3008>__)
• Fixed assert_hostname=False to correctly skip hostname check. (#&#8203;3051 <https://github.com/urllib3/urllib3/issues/3051>__)

v2.0.2

Compare Source

==================

• Fixed HTTPResponse.stream() to continue yielding bytes if buffered decompressed data
  was still available to be read even if the underlying socket is closed. This prevents
  a compressed response from being truncated. (#&#8203;3009 <https://github.com/urllib3/urllib3/issues/3009>__)

v2.0.1

Compare Source

==================

• Fixed a socket leak when fingerprint or hostname verifications fail. (#&#8203;2991 <https://github.com/urllib3/urllib3/issues/2991>__)
• Fixed an error when HTTPResponse.read(0) was the first read call or when the internal response body buffer was otherwise empty. (#&#8203;2998 <https://github.com/urllib3/urllib3/issues/2998>__)

v2.0.0

Compare Source

==================

Read the v2.0 migration guide <https://urllib3.readthedocs.io/en/latest/v2-migration-guide.html>__ for help upgrading to the latest version of urllib3.

Removed

• Removed support for Python 2.7, 3.5, and 3.6 (#&#8203;883 <https://github.com/urllib3/urllib3/issues/883>, #&#8203;2336 <https://github.com/urllib3/urllib3/issues/2336>).
• Removed fallback on certificate commonName in match_hostname() function.
  This behavior was deprecated in May 2000 in RFC 2818. Instead only subjectAltName
  is used to verify the hostname by default. To enable verifying the hostname against
  commonName use SSLContext.hostname_checks_common_name = True (#&#8203;2113 <https://github.com/urllib3/urllib3/issues/2113>__).
• Removed support for Python with an ssl module compiled with LibreSSL, CiscoSSL,
  wolfSSL, and all other OpenSSL alternatives. Python is moving to require OpenSSL with PEP 644 (#&#8203;2168 <https://github.com/urllib3/urllib3/issues/2168>__).
• Removed support for OpenSSL versions earlier than 1.1.1 or that don't have SNI support.
  When an incompatible OpenSSL version is detected an ImportError is raised (#&#8203;2168 <https://github.com/urllib3/urllib3/issues/2168>__).
• Removed the list of default ciphers for OpenSSL 1.1.1+ and SecureTransport as their own defaults are already secure (#&#8203;2082 <https://github.com/urllib3/urllib3/issues/2082>__).
• Removed urllib3.contrib.appengine.AppEngineManager and support for Google App Engine Standard Environment (#&#8203;2044 <https://github.com/urllib3/urllib3/issues/2044>__).
• Removed deprecated Retry options method_whitelist, DEFAULT_REDIRECT_HEADERS_BLACKLIST (#&#8203;2086 <https://github.com/urllib3/urllib3/issues/2086>__).
• Removed urllib3.HTTPResponse.from_httplib (#&#8203;2648 <https://github.com/urllib3/urllib3/issues/2648>__).
• Removed default value of None for the request_context parameter of urllib3.PoolManager.connection_from_pool_key. This change should have no effect on users as the default value of None was an invalid option and was never used (#&#8203;1897 <https://github.com/urllib3/urllib3/issues/1897>__).
• Removed the urllib3.request module. urllib3.request.RequestMethods has been made a private API.
  This change was made to ensure that from urllib3 import request imported the top-level request()
  function instead of the urllib3.request module (#&#8203;2269 <https://github.com/urllib3/urllib3/issues/2269>__).
• Removed support for SSLv3.0 from the urllib3.contrib.pyopenssl even when support is available from the compiled OpenSSL library (#&#8203;2233 <https://github.com/urllib3/urllib3/issues/2233>__).
• Removed the deprecated urllib3.contrib.ntlmpool module (#&#8203;2339 <https://github.com/urllib3/urllib3/issues/2339>__).
• Removed DEFAULT_CIPHERS, HAS_SNI, USE_DEFAULT_SSLCONTEXT_CIPHERS, from the private module urllib3.util.ssl_ (#&#8203;2168 <https://github.com/urllib3/urllib3/issues/2168>__).
• Removed urllib3.exceptions.SNIMissingWarning (#&#8203;2168 <https://github.com/urllib3/urllib3/issues/2168>__).
• Removed the _prepare_conn method from HTTPConnectionPool. Previously this was only used to call HTTPSConnection.set_cert() by HTTPSConnectionPool (#&#8203;1985 <https://github.com/urllib3/urllib3/issues/1985>__).
• Removed tls_in_tls_required property from HTTPSConnection. This is now determined from the scheme parameter in HTTPConnection.set_tunnel() (#&#8203;1985 <https://github.com/urllib3/urllib3/issues/1985>__).
• Removed the strict parameter/attribute from HTTPConnection, HTTPSConnection, HTTPConnectionPool, HTTPSConnectionPool, and HTTPResponse (#&#8203;2064 <https://github.com/urllib3/urllib3/issues/2064>__).

Deprecated

• Deprecated HTTPResponse.getheaders() and HTTPResponse.getheader() which will be removed in urllib3 v2.1.0. Instead use HTTPResponse.headers and HTTPResponse.headers.get(name, default). (#&#8203;1543 <https://github.com/urllib3/urllib3/issues/1543>, #&#8203;2814 <https://github.com/urllib3/urllib3/issues/2814>).
• Deprecated urllib3.contrib.pyopenssl module which will be removed in urllib3 v2.1.0 (#&#8203;2691 <https://github.com/urllib3/urllib3/issues/2691>__).
• Deprecated urllib3.contrib.securetransport module which will be removed in urllib3 v2.1.0 (#&#8203;2692 <https://github.com/urllib3/urllib3/issues/2692>__).
• Deprecated ssl_version option in favor of ssl_minimum_version. ssl_version will be removed in urllib3 v2.1.0 (#&#8203;2110 <https://github.com/urllib3/urllib3/issues/2110>__).
• Deprecated the strict parameter of PoolManager.connection_from_context() as it's not longer needed in Python 3.x. It will be removed in urllib3 v2.1.0 (#&#8203;2267 <https://github.com/urllib3/urllib3/issues/2267>__)
• Deprecated the NewConnectionError.pool attribute which will be removed in urllib3 v2.1.0 (#&#8203;2271 <https://github.com/urllib3/urllib3/issues/2271>__).
• Deprecated format_header_param_html5 and format_header_param in favor of format_multipart_header_param (#&#8203;2257 <https://github.com/urllib3/urllib3/issues/2257>__).
• Deprecated RequestField.header_formatter parameter which will be removed in urllib3 v2.1.0 (#&#8203;2257 <https://github.com/urllib3/urllib3/issues/2257>__).
• Deprecated HTTPSConnection.set_cert() method. Instead pass parameters to the HTTPSConnection constructor (#&#8203;1985 <https://github.com/urllib3/urllib3/issues/1985>__).
• Deprecated HTTPConnection.request_chunked() method which will be removed in urllib3 v2.1.0. Instead pass chunked=True to HTTPConnection.request() (#&#8203;1985 <https://github.com/urllib3/urllib3/issues/1985>__).

Added

• Added top-level urllib3.request function which uses a preconfigured module-global PoolManager instance (#&#8203;2150 <https://github.com/urllib3/urllib3/issues/2150>__).
• Added the json parameter to urllib3.request(), PoolManager.request(), and ConnectionPool.request() methods to send JSON bodies in requests. Using this parameter will set the header Content-Type: application/json if Content-Type isn't already defined.
  Added support for parsing JSON response bodies with HTTPResponse.json() method (#&#8203;2243 <https://github.com/urllib3/urllib3/issues/2243>__).
• Added type hints to the urllib3 module (#&#8203;1897 <https://github.com/urllib3/urllib3/issues/1897>__).
• Added ssl_minimum_version and ssl_maximum_version options which set
  SSLContext.minimum_version and SSLContext.maximum_version (#&#8203;2110 <https://github.com/urllib3/urllib3/issues/2110>__).
• Added support for Zstandard (RFC 8878) when zstandard 1.18.0 or later is installed.
  Added the zstd extra which installs the zstandard package (#&#8203;1992 <https://github.com/urllib3/urllib3/issues/1992>__).
• Added urllib3.response.BaseHTTPResponse class. All future response classes will be subclasses of BaseHTTPResponse (#&#8203;2083 <https://github.com/urllib3/urllib3/issues/2083>__).
• Added FullPoolError which is raised when PoolManager(block=True) and a connection is returned to a full pool (#&#8203;2197 <https://github.com/urllib3/urllib3/issues/2197>__).
• Added HTTPHeaderDict to the top-level urllib3 namespace (#&#8203;2216 <https://github.com/urllib3/urllib3/issues/2216>__).
• Added support for configuring header merging behavior with HTTPHeaderDict
  When using a HTTPHeaderDict to provide headers for a request, by default duplicate
  header values will be repeated. But if combine=True is passed into a call to
  HTTPHeaderDict.add, then the added header value will be merged in with an existing
  value into a comma-separated list (X-My-Header: foo, bar) (#&#8203;2242 <https://github.com/urllib3/urllib3/issues/2242>__).
• Added NameResolutionError exception when a DNS error occurs (#&#8203;2305 <https://github.com/urllib3/urllib3/issues/2305>__).
• Added proxy_assert_hostname and proxy_assert_fingerprint kwargs to ProxyManager (#&#8203;2409 <https://github.com/urllib3/urllib3/issues/2409>__).
• Added a configurable backoff_max parameter to the Retry class.
  If a custom backoff_max is provided to the Retry class, it
  will replace the Retry.DEFAULT_BACKOFF_MAX (#&#8203;2494 <https://github.com/urllib3/urllib3/issues/2494>__).
• Added the authority property to the Url class as per RFC 3986 3.2. This property should be used in place of netloc for users who want to include the userinfo (auth) component of the URI (#&#8203;2520 <https://github.com/urllib3/urllib3/issues/2520>__).
• Added the scheme parameter to HTTPConnection.set_tunnel to configure the scheme of the origin being tunnelled to (#&#8203;1985 <https://github.com/urllib3/urllib3/issues/1985>__).
• Added the is_closed, is_connected and has_connected_to_proxy properties to HTTPConnection (#&#8203;1985 <https://github.com/urllib3/urllib3/issues/1985>__).
• Added optional backoff_jitter parameter to Retry. (#&#8203;2952 <https://github.com/urllib3/urllib3/issues/2952>__)

Changed

• Changed urllib3.response.HTTPResponse.read to respect the semantics of io.BufferedIOBase regardless of compression. Specifically, this method:

  • Only returns an empty bytes object to indicate EOF (that is, the response has been fully consumed).
  • Never returns more bytes than requested.
  • Can issue any number of system calls: zero, one or multiple.

  If you want each urllib3.response.HTTPResponse.read call to issue a single system call, you need to disable decompression by setting decode_content=False (#&#8203;2128 <https://github.com/urllib3/urllib3/issues/2128>__).

• Changed urllib3.HTTPConnection.getresponse to return an instance of urllib3.HTTPResponse instead of http.client.HTTPResponse (#&#8203;2648 <https://github.com/urllib3/urllib3/issues/2648>__).

• Changed ssl_version to instead set the corresponding SSLContext.minimum_version
  and SSLContext.maximum_version values. Regardless of ssl_version passed
  SSLContext objects are now constructed using ssl.PROTOCOL_TLS_CLIENT (#&#8203;2110 <https://github.com/urllib3/urllib3/issues/2110>__).

• Changed default SSLContext.minimum_version to be TLSVersion.TLSv1_2 in line with Python 3.10 (#&#8203;2373 <https://github.com/urllib3/urllib3/issues/2373>__).

• Changed ProxyError to wrap any connection error (timeout, TLS, DNS) that occurs when connecting to the proxy (#&#8203;2482 <https://github.com/urllib3/urllib3/pull/2482>__).

• Changed urllib3.util.create_urllib3_context to not override the system cipher suites with
  a default value. The new default will be cipher suites configured by the operating system (`#​2168 <htt

❗ Important

✂ PR body was truncated to here.