aio-libs/aiohttp v3.14.0

3.14.0

on GitHub

We have a new website! https://aio-libs.org
Subscribe to the news feed to find out more about what we're working on in future.

Features

• Added RequestKey and ResponseKey classes,
  which enable static type checking for request & response
  context storages in the same way that AppKey does for Application
  -- by :user:gsoldatov.

  Related issues and pull requests on GitHub:
  #11766.

• Added :func:~aiohttp.encode_basic_auth for encoding HTTP Basic
  Authentication credentials. Replaces the now-deprecated
  :class:~aiohttp.BasicAuth -- by :user:Dreamsorcerer.

  Related issues and pull requests on GitHub:
  #12499.

• Started accepting :term:asynchronous context managers <asynchronous context manager> for cleanup contexts.
  Legacy single-yield :term:asynchronous generator cleanup contexts continue to be
  supported; async context managers are adapted internally so they are
  entered at startup and exited during cleanup.

  -- by :user:MannXo.

  Related issues and pull requests on GitHub:
  #11681.

• Added :py:attr:~aiohttp.CookieJar.cookies and :py:attr:~aiohttp.CookieJar.host_only_cookies read-only properties to :py:class:~aiohttp.CookieJar exposing the stored cookies with their full attributes -- by :user:Br1an67.

  Related issues and pull requests on GitHub:
  #3951.

• Added :py:attr:~aiohttp.web.TCPSite.port accessor for dynamic port allocations in :class:~aiohttp.web.TCPSite -- by :user:twhittock-disguise and :user:rodrigobnogueira.

  Related issues and pull requests on GitHub:
  #10665.

• Added decode_text parameter to :meth:~aiohttp.ClientSession.ws_connect and :class:~aiohttp.web.WebSocketResponse to receive WebSocket TEXT messages as raw bytes instead of decoded strings, enabling direct use with high-performance JSON parsers like orjson -- by :user:bdraco.

  Related issues and pull requests on GitHub:
  #11763, #11764.

• Large overhaul of parser/decompression code.

  The zip bomb security fix in 3.13 stopped highly compressed payloads
  from being decompressed, regardless of validity. Now aiohttp will
  decompress such payloads in chunks of 256+ KiB, allowing safe decompression
  of such payloads.

  -- by :user:Dreamsorcerer.

  Related issues and pull requests on GitHub:
  #11966.

• Added explicit APIs for bytes-returning JSON serializer:
  JSONBytesEncoder type, JsonBytesPayload,
  :func:~aiohttp.web.json_bytes_response,
  :meth:~aiohttp.web.WebSocketResponse.send_json_bytes and
  :meth:~aiohttp.ClientWebSocketResponse.send_json_bytes methods, and
  json_serialize_bytes parameter for :class:~aiohttp.ClientSession
  -- by :user:kevinpark1217.

  Related issues and pull requests on GitHub:
  #11989.

• Added :attr:~aiohttp.ClientResponse.output_size and
  :attr:~aiohttp.ClientResponse.upload_complete -- by :user:Dreamsorcerer.

  Related issues and pull requests on GitHub:
  #12452.

Bug fixes

• Fixed ZLibDecompressor silently dropping data past the first
  member when decompressing concatenated gzip/deflate streams. Each subsequent
  member is now handed to a fresh decompressor, matching the behaviour already
  implemented for ZSTD multi-frame streams.

  -- by :user:Ashutosh-177

  Related issues and pull requests on GitHub:
  #7157.

• Improved the parser error message shown when TLS handshake bytes are received on an HTTP port -- by :user:puneetdixit200.

  Related issues and pull requests on GitHub:
  #10142.

• Fixed the C parser failing to reject a response with a body when none was expected -- by :user:Dreamsorcerer.

  Related issues and pull requests on GitHub:
  #10587.

• Fixed http parser not rejecting HTTP/1.1 requests that do not have valid Host header.
  -- by :user:Cycloctane.

  Related issues and pull requests on GitHub:
  #10600.

• Fixed misleading TLS-in-TLS warning being emitted when sending HTTPS requests through an HTTP proxy. The warning now only fires when the proxy itself uses HTTPS, which is the only case where TLS-in-TLS actually applies -- by :user:wavebyrd.

  Related issues and pull requests on GitHub:
  #10683.

• Fixed AssertionError when the transport is None during WebSocket
  preparation or file response sending (e.g. when a client disconnects
  immediately after connecting). A ConnectionResetError is now raised
  instead -- by :user:agners.

  Related issues and pull requests on GitHub:
  #11761.

• Fixed ad-hoc cookies passed to individual requests not being sent when the session's cookie jar has unsafe=True and the target URL uses an IP address, by copying the unsafe setting from the session's cookie jar to the temporary cookie jar -- by :user:Krishnachaitanyakc.

  Related issues and pull requests on GitHub:
  #12011.

• Reset the WebSocket heartbeat timer on inbound data to avoid false ping/pong timeouts while receiving large frames
  -- by :user:hoffmang9.

  Related issues and pull requests on GitHub:
  #12030.

• Switched :py:meth:~aiohttp.CookieJar.save to use JSON format and
  :py:meth:~aiohttp.CookieJar.load to try JSON first with a fallback to
  a restricted pickle unpickler -- by :user:YuvalElbar6.

  Related issues and pull requests on GitHub:
  #12091.

• Fixed redirects with consumed non-rewindable request bodies to raise
  :class:aiohttp.ClientPayloadError instead of silently sending an empty body.

  Related issues and pull requests on GitHub:
  #12195.

• Fixed zstd decompression failing with ClientPayloadError when the server
  sends a response as multiple zstd frames -- by :user:josu-moreno.

  Related issues and pull requests on GitHub:
  #12234.

• Fixed spurious Future exception was never retrieved warning on disconnect during back-pressure -- by :user:availov.

  Related issues and pull requests on GitHub:
  #12281.

• Cookiejar.save() now uses 0x600 permissions to better protect them from being read by other users -- by :user:digiscrypt.

  Related issues and pull requests on GitHub:
  #12312.

• Fixed a crash (:external+python:exc:~http.cookies.CookieError) in the cookie parser when receiving cookies
  containing ASCII control characters on CPython builds with the :cve:2026-3644
  patch. The parser now gracefully skips cookies whose value contains control
  characters instead of letting the exception propagate -- by :user:rodrigobnogueira.

  Related issues and pull requests on GitHub:
  #12395.

• Fixed digest authentication failing for requests whose path or query string contains percent-encoded reserved characters; the digest signature now uses the encoded request-target that is sent on the wire instead of the decoded form -- by :user:bdraco.

  Related issues and pull requests on GitHub:
  #12436.

• Fixed :func:aiohttp.web.run_app losing inner traceback frames when an
  exception is raised during application startup (e.g. inside
  cleanup_ctx or on_startup). Regression since 3.10.6.

  Related issues and pull requests on GitHub:
  #12493.

• Fixed per-request cookies not being dropped on cross-origin redirects -- by :user:Dreamsorcerer.

  Related issues and pull requests on GitHub:
  #12550.

• Fixed invalid bytes being allowed in multipart/payload headers -- by :user:Dreamsorcerer.

  Related issues and pull requests on GitHub:
  #12719.

• Fixed :py:meth:~aiohttp.FormData.add_field accepting invalid bytes in name and filename -- by :user:Dreamsorcerer.

  Related issues and pull requests on GitHub:
  #12721.

• Fixed websocket upgrade occurring when header contained a value like notupgrade -- by :user:Dreamsorcerer.

  Related issues and pull requests on GitHub:
  #12723.

Deprecations (removal in next major release)

• Deprecated :class:~aiohttp.BasicAuth and the auth / proxy_auth
  parameters. They will be removed in aiohttp 4.0. Use the new
  :func:~aiohttp.encode_basic_auth helper together with
  headers={"Authorization": ...} (or
  proxy_headers={"Proxy-Authorization": ...} for proxies) instead.
  Note that encode_basic_auth() defaults to utf-8, not latin1
  -- by :user:Dreamsorcerer.

  Related issues and pull requests on GitHub:
  #12499.

• Added deprecation warning to aiohttp.pytest_plugin, please switch to pytest-aiohttp -- by :user:Dreamsorcerer.

  Related issues and pull requests on GitHub:
  #10785.

Removals and backward incompatible breaking changes

• Stopped calling :func:socket.getfqdn as the fallback for
  :attr:aiohttp.web.BaseRequest.host. :func:socket.getfqdn
  performs blocking reverse DNS resolution on the event loop
  thread and can stall a worker for many seconds when the system
  resolver is slow, and could be triggered remotely by an HTTP/1.0
  request that omits the Host header. The fallback when no
  Host header is present is now the local socket address the
  request arrived on (transport sockname), or an empty string
  if no transport information is available. Code that relied on
  the FQDN being returned must now read it from
  :func:socket.getfqdn directly, off the event loop
  -- by :user:bdraco.

  Related issues and pull requests on GitHub:
  #9308, #12597.

• Dropped support for Python 3.9 -- by :user:Dreamsorcerer.

  Related issues and pull requests on GitHub:
  #11601.

• Tightened outbound header serialization to reject all ASCII control
  characters forbidden by :rfc:9110#section-5.5 and :rfc:9112#section-4
  (0x00-0x08, 0x0A-0x1F, 0x7F) in status lines,
  header field-names, and field-values. Previously only CR, LF and NUL were
  rejected. HTAB (0x09) remains permitted in field values. Applications
  that placed bare control characters in outbound headers will now raise
  :exc:ValueError instead of emitting non-RFC-compliant bytes -- by :user:rodrigobnogueira.

  Related issues and pull requests on GitHub:
  #12689.

Improved documentation

• Replaced the deprecated ujson library with orjson in the
  client quickstart documentation. ujson has been put into
  maintenance-only mode; orjson is the recommended alternative.
  -- by :user:indoor47

  Related issues and pull requests on GitHub:
  #10795.

• Added the :doc:threat_model to the Sphinx documentation -- by :user:omkar-334.

  Related issues and pull requests on GitHub:
  #12549.

• Removed archived and deprecated repositories from third party list -- by :user:Polandia94.

  Related issues and pull requests on GitHub:
  #12726.

• Added aiointercept to list of third-party libraries -- by :user:Polandia94.

  Related issues and pull requests on GitHub:
  #12727.

Packaging updates and notes for downstreams

• Added wheels for Android and iOS platforms -- by :user:timrid.

  Related issues and pull requests on GitHub:
  #11750.

• Parallelized the Cython extension compilation by defaulting
  build_ext.parallel to os.cpu_count(), so each module's
  gcc invocation now runs concurrently instead of one at a time
  -- by :user:bdraco.

  Related issues and pull requests on GitHub:
  #12576.

• Submitted vendored llhttp to Github's SBOM -- by :user:Dreamsorcerer.

  Related issues and pull requests on GitHub:
  #12678.

• Updated llhttp to v9.4.1 -- by :user:Dreamsorcerer.

  Related issues and pull requests on GitHub:
  #12681.

Contributor-facing changes

• The coverage tool is now configured using the new native
  auto-discovered :file:.coveragerc.toml file
  -- by :user:webknjaz.

  It is also set up to use the ctrace core that works
  around the performance issues in the sysmon tracer
  which is default under Python 3.14.

  Related issues and pull requests on GitHub:
  #11826.

• Fixed and reworked autobahn tests -- by :user:Dreamsorcerer.

  Related issues and pull requests on GitHub:
  #12173.

• Added a CI job to measure Cython coverage -- by :user:Dreamsorcerer.

  Related issues and pull requests on GitHub:
  #12349.

• Disabled coverage and xdist by default to ease local development -- by :user:Dreamsorcerer.

  Related issues and pull requests on GitHub:
  #12364.

• Avoid installation of backports.zstd on Python 3.14 in linting dependency set
  -- by :user:seifertm.

  Related issues and pull requests on GitHub:
  #12406.

• Added --durations=30 to the benchmark CI run so the slowest tests are reported when the job hits its timeout -- by :user:aiolibsbot.

  Related issues and pull requests on GitHub:
  #12562.

• Fixed two flakey test_middleware_uses_session_avoids_recursion_with_* tests
  that hard coded localhost in the inner middleware request; they now target
  the bound server URL so happy eyeballs cannot pick an unbound address on
  Windows runners -- by :user:bdraco.

  Related issues and pull requests on GitHub:
  #12571.

• Restricted the isal test dependency to CPython, since
  isal 1.8.0 stopped publishing PyPy wheels and the source
  build requires nasm, which is not available on the CI
  runners. The parametrize_zlib_backend fixture already
  calls pytest.importorskip, so PyPy continues to exercise
  the zlib and zlib_ng backends with no further
  changes -- by :user:bdraco.

  Related issues and pull requests on GitHub:
  #12589.

• Fixed a flakey test_tcp_connector_fingerprint_ok by aborting
  the SSL shutdown on the test's TCP connector before returning.
  The graceful TLS close was occasionally outliving the test event
  loop on one of the CI jobs, and the teardown gc.collect()
  then surfaced the still-open transport as a
  PytestUnraisableExceptionWarning -- by :user:bdraco.

  Related issues and pull requests on GitHub:
  #12592.

• Switched the cibuildwheel build frontend to build[uv] so
  that uv provisions every build-isolation virtual environment
  in the wheel matrix, replacing the per-ABI pip resolve with a
  roughly sub-second uv resolve
  -- by :user:bdraco.

  Related issues and pull requests on GitHub:
  #12595.

• Fixed flaky test_handler_returns_not_response and
  test_handler_returns_none by routing loop.set_debug(True)
  through a new loop_debug_mode fixture that disables debug
  mode before the aiohttp_client fixture finalizes. Leaving
  debug on through teardown let PyPy 3.11's asyncio slow-callback
  logger walk into Task.__repr__ during connector close,
  surfacing a spurious RuntimeWarning: coroutine was never awaited -- by :user:bdraco.

  Related issues and pull requests on GitHub:
  #12603.

• Reduced runtime of several of the slowest unit tests
  (decompress size-limit payloads from 64 MiB to 2 MiB,
  test_chunk_splits_after_pause chunk count from 50000
  to 20000, and test_set_cookies_max_age sleep from 2
  seconds to 1.1 seconds) without changing what they
  exercise -- by :user:bdraco.

  Related issues and pull requests on GitHub:
  #12606.

• Added a default 120-second per-test timeout via pytest-timeout so a
  hung test surfaces by name in CI output instead of getting hidden behind
  the job-level timeout added in :pr:12619. The autobahn and
  benchmark jobs opt out with --timeout=0 -- by :user:bdraco.

  Related issues and pull requests on GitHub:
  #12624.

• Switched the CI test and autobahn jobs from
  actions/setup-python to astral-sh/setup-uv for installing
  interpreters, cutting the Setup Python step from 40-58s to a
  few seconds on macos-latest and windows-latest runners for
  variants not in the hosted tool-cache (notably the free-threaded
  3.14t)
  -- by :user:bdraco.

  Related issues and pull requests on GitHub:
  #12629.

• Made the pip command used by the :file:Makefile configurable via a
  PIP variable; downstream consumers can now run, for example,
  make .develop PIP="uv pip" to install via uv without us
  maintaining a parallel target
  -- by :user:bdraco.

  Related issues and pull requests on GitHub:
  #12641.

• Allowed re-running the deploy job in .github/workflows/ci-cd.yml
  after a partial release failure: the Make Release step now skips
  when the GitHub Release already exists, and the PyPI publish step uses
  skip-existing so dists that were already uploaded on a prior
  attempt do not break the retry -- by :user:bdraco.

  Related issues and pull requests on GitHub:
  #12651.

• Switched the armv7l wheel builds onto GitHub's hosted ARM runners. The
  32-bit ARM build still runs under QEMU, but the host is now aarch64
  rather than x86_64, so the emulation overhead drops sharply
  -- by :user:bdraco.

  Related issues and pull requests on GitHub:
  #12655.

Miscellaneous internal changes

• Added win_arm64 to the wheels that gets pushed to PyPI
  -- by :user:AraHaan.

  Related issues and pull requests on GitHub:
  #11937.

• Added cdef type declarations and inlined the upgrade check in the HTTP parser
  -- by :user:bdraco.

  Related issues and pull requests on GitHub:
  #12321.

• Changed zlib_executor_size default so compressed payloads are async by default -- by :user:Dreamsorcerer.

  Related issues and pull requests on GitHub:
  #12358.

• Added THREAT_MODEL.md detailing our security stance -- by :user:Dreamsorcerer.

  Related issues and pull requests on GitHub:
  #12512.

• Reduced payload sizes and request counts in the slowest client and URL
  dispatcher benchmarks so they no longer dominate CI runtime
  -- by :user:bdraco.

  Related issues and pull requests on GitHub:
  #12569.

• Improved ContentLengthError exception messages to include both expected and received byte counts. This enhancement provides better diagnostics when debugging response body size mismatches
  -- by :user:bdraco and :user:Dreamsorcerer.

  Related issues and pull requests on GitHub:
  #12753.