aiohttp 3.14.0 on Python PyPI

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.