aio-libs/aiohttp · error · RuntimeError

aiohttp 4.x requires Python 3.10+

Error message

aiohttp 4.x requires Python 3.10+

What it means

Raised by setup.py at the top level when sys.version_info is below (3, 10). aiohttp 4.x dropped support for Python 3.9 and earlier, so setup.py hard-aborts install/build (pip install, pip install -e, setup.py develop) on an unsupported interpreter before any compilation happens. This surfaces the requirement early instead of failing later in Cython compilation.

Solutions

1. Upgrade the runtime to Python 3.10+ (3.11/3.12 recommended) and reinstall.
2. If you cannot upgrade Python, stay on the aiohttp 3.x release line (`pip install 'aiohttp<4'`).
3. Update pyproject.toml / tox / CI `python-version` matrices to drop 3.9 when adopting aiohttp 4.

Example fix

// before
$ python --version
Python 3.9.18
$ pip install -e .
RuntimeError: aiohttp 4.x requires Python 3.10+

// after
$ python3.12 -m venv .venv && source .venv/bin/activate
$ pip install -e .   # ok
# or, stuck on 3.9:
$ pip install 'aiohttp<4'

import sys
assert sys.version_info >= (3, 10), 'aiohttp 4.x requires Python 3.10+'

def python_supports_aiohttp4() -> bool:
    import sys
    return sys.version_info >= (3, 10)

# raised at install time; pin a compatible interpreter or aiohttp line.
# In CI matrix selection:
try:
    subprocess.check_call([sys.executable, '-m', 'pip', 'install', '-e', '.'])
except SystemExit:
    subprocess.check_call([sys.executable, '-m', 'pip', 'install', "'aiohttp<4'"])

When it happens

Trigger: Running `pip install aiohttp`, `pip install -e .`, or `python setup.py ...` with an active Python 3.9 or older interpreter against the aiohttp 4.x source tree.

Common situations: Upgrading a project pinned to Python 3.9 from aiohttp 3.x to 4.x; CI matrix that still includes 3.9; a Docker base image tagged python:3.9.

Related errors

• Use Python 3.11+ to run 'make sync-direct-runtime-deps'
• Cannot initialize a TLS-in-TLS connection to host

AI-assisted analysis of aio-libs/aiohttp@d041d4d0fd (2026-08-11). Data as JSON: /api/errors/44aa01424d2cf8aa. Report an issue: GitHub.

Appendix: source

Thrown at setup.py:9

import os
import pathlib
import sys

from setuptools import Extension, setup
from setuptools.command.build_ext import build_ext

if sys.version_info < (3, 10):
    raise RuntimeError("aiohttp 4.x requires Python 3.10+")


USE_SYSTEM_DEPS = bool(
    os.environ.get("AIOHTTP_USE_SYSTEM_DEPS", os.environ.get("USE_SYSTEM_DEPS"))
)
NO_EXTENSIONS: bool = bool(os.environ.get("AIOHTTP_NO_EXTENSIONS"))
CYTHON_TRACING: bool = bool(os.environ.get("AIOHTTP_CYTHON_TRACE"))
HERE = pathlib.Path(__file__).parent
IS_GIT_REPO = (HERE / ".git").exists()


if sys.implementation.name != "cpython":
    NO_EXTENSIONS = True


if (
    not USE_SYSTEM_DEPS
    and IS_GIT_REPO

View on GitHub (pinned to d041d4d0fd)