ModuleNotFoundError: No Module Named ‘aiohttp’
ModuleNotFoundError: No module named 'aiohttp' means the Python interpreter running your code cannot find the aiohttp package in its current environment. Usually, aiohttp is not installed for that interpreter, but the error can also mean that pip, VS Code, a notebook kernel, Docker image, or deployment is using a different Python environment than the one where you installed it.
Use this table to identify the likely cause before changing anything.
| Symptom | Likely Cause | Fix |
|---|---|---|
| The first import fails immediately | aiohttp is not installed |
Install it with the same interpreter that runs the app. |
| Installation says “Requirement already satisfied” but import still fails | pip installed into a different environment or user site directory |
Compare the Python and pip locations, then install through python -m pip. |
| VS Code shows an import warning | VS Code selected a different interpreter than your terminal or project environment | Select the project interpreter, then verify the import in VS Code’s terminal. |
| A Jupyter notebook fails but a terminal works | The notebook kernel uses another Python executable | Install into the kernel’s interpreter and restart the kernel. |
| A Docker container or server fails after local success | The dependency is absent from the image or deployment environment | Add aiohttp to the project dependency file and rebuild or redeploy. |
| The error occurs inside an async SDK client | An optional or undeclared async transport dependency is missing | Install and declare aiohttp in the application environment. |
What the aiohttp Error Means
aiohttp is a third-party Python package for asynchronous HTTP clients, HTTP servers, and WebSocket applications. It is not part of Python’s standard library, so Python can import it only after it has been installed into the environment used by your program.
A typical failing import looks like this:
import aiohttp
Python searches the directories listed in sys.path. If it cannot find an installed aiohttp package in those locations, it raises:
ModuleNotFoundError: No module named 'aiohttp'
The import name must be lowercase:
import aiohttp
Python is case-sensitive for module names. import AIOHTTP looks for a different module named AIOHTTP and will fail even if aiohttp is installed.
How to Fix ModuleNotFoundError for aiohttp
Use the Python interpreter that runs the application to install aiohttp, then verify the import before rerunning it.
Step 1: Identify the Python Interpreter Running the Code
First, determine which Python executable should run the project. Run this from the same terminal, virtual environment, container, or task runner you use to start the application.
On macOS or Linux:
python -c "import sys; print(sys.executable); print(sys.version)"
If your project uses python3 rather than python, run:
python3 -c "import sys; print(sys.executable); print(sys.version)"
On Windows, when using the Python launcher:
py -c "import sys; print(sys.executable); print(sys.version)"
The printed executable path is the Python installation that needs aiohttp.
I reproduce one problem at a time in a clean virtual environment because it removes machine-specific noise.
Step 2: Activate or Create the Intended Virtual Environment
If the project already has a virtual environment, activate that environment before installing packages. Do not install globally if the application runs from a project virtual environment.
To create a new environment in the project directory:
python -m venv .venv
Activate it on macOS or Linux:
source .venv/bin/activate
Activate it in Windows PowerShell:
.venv\Scripts\Activate.ps1
Activate it in Windows Command Prompt:
.venv\Scripts\activate.bat
After activation, run the command that prints sys.executable in the active shell. Its path should point into the .venv directory.
If the project already has dependency files such as requirements.txt or pyproject.toml, use its normal setup process rather than installing only one package whenever possible. The project may require related packages and compatible versions.
Step 3: Install aiohttp Through That Interpreter
Install aiohttp through the interpreter that runs the application:
python -m pip install aiohttp
For projects launched with python3:
python3 -m pip install aiohttp
For the Windows Python launcher:
py -m pip install aiohttp
Using python -m pip is more reliable than using a bare pip command because it runs pip through the selected Python interpreter. It also works when a separate pip executable is not available in your system PATH.
Avoid using administrator or sudo installation commands to fix a project environment. They can install the package for a system Python while your app continues to use a virtual environment without it.
Step 4: Verify the Import Before Rerunning the Application
Confirm that the same Python executable can find the package:
python -c "import sys, aiohttp; print(sys.executable); print(aiohttp.__file__)"
A successful result prints two paths:
- the Python executable being used
- the installed location of
aiohttp
Then rerun the command, test suite, server, or script that originally failed. If the direct import succeeds but the application still raises the error, the application is being launched by a different interpreter, container, worker, or notebook kernel.
When aiohttp Is Installed but Still Cannot Be Imported
A successful pip message proves only that one installation target has aiohttp; it does not prove that the running application uses that target.
This is the most common explanation for “Requirement already satisfied” followed by ModuleNotFoundError.
On macOS or Linux, compare the paths used by Python and a standalone pip command:
which python
which pip
Then check the pip attached directly to the current Python:
python -m pip --version
On Windows, inspect available executables with:
where python
where pip
The location printed by python -m pip --version should belong to the environment shown by python -c "import sys; print(sys.executable)". If they point to different installations, activate the intended virtual environment and install aiohttp again through that interpreter.
User Installs and Missing User Site Paths
A user-level installation can be useful when you intentionally use a user-managed Python environment:
python -m pip install --user aiohttp
However, this is not a substitute for installing into a virtual environment. A package installed under a user directory such as .local may not be included in the runtime’s import path. This can produce the confusing combination of a successful installation message and a failed import.
Use a project virtual environment for applications, services, and repeatable development setups.
Clean Reinstall When the Environment Is Correct
If Python and pip clearly point to the same environment but the import still fails, remove and reinstall the package.
With the interpreter-bound approach:
python -m pip uninstall aiohttp
Enter y when pip asks whether to remove the installed copy. Then reinstall it:
python -m pip install aiohttp
If your application is specifically launched with python3 and its matching package tool is pip3, the equivalent removal command is:
pip3 uninstall aiohttp
After reinstalling, run python -c “import sys, aiohttp; print(sys.executable); print(aiohttp.__file__)” before starting the full application.
Fixing aiohttp in VS Code, Jupyter, Conda, and Docker
VS Code Import Warnings
A VS Code warning such as “Import aiohttp could not be resolved” often means the editor’s Python extension is inspecting a different environment than the terminal.
Use the Command Palette and select Python: Select Interpreter, then choose the interpreter inside your project environment. Open a new integrated terminal and verify the active interpreter:
python -c "import sys, aiohttp; print(sys.executable); print(aiohttp.__file__)"
If the terminal test succeeds but the warning remains, reload the editor window or restart the Python language service after confirming the selected interpreter. The runtime import test is the important check; a static-analysis warning is not the same as a runtime failure.
Jupyter Notebooks
A notebook kernel can use a different environment from your normal terminal. Run this in a notebook cell to install into the kernel’s Python executable:
import sys
!{sys.executable} -m pip install aiohttp
Restart the notebook kernel after installation, then test:
import aiohttp
Restarting matters because the active kernel may have loaded package information before the installation completed.
Conda Environments
If the project is managed with Conda, activate the intended Conda environment first and use the package manager your project expects. A Conda-based installation is:
conda install -c conda-forge aiohttp
You can also use interpreter-bound pip inside an activated Conda environment when that is how the project manages Python dependencies:
python -m pip install aiohttp
Do not mix Conda and pip casually in a shared environment. Check the project’s dependency files and existing setup before changing package managers.
Docker, CI, and Remote Deployments
Declare aiohttp in the project dependency file before building or deploying the project. The dependency must be declared in the project so each environment installs it during its build.
For a requirements.txt project, include this line:
aiohttp
A Dockerfile should install the dependency file inside the image:
RUN python -m pip install --no-cache-dir -r requirements.txt
Rebuild the image or redeploy after changing the dependency file. A working local environment and a failing container almost always indicate that the container was built without the same dependency set.
Errors Inside Other Libraries and aiohttp.web
Sometimes your code does not import aiohttp directly. Instead, a traceback inside an async SDK, HTTP client, or cloud library may eventually show:
ModuleNotFoundError: No module named 'aiohttp'
That library may use aiohttp as an optional async transport. Install aiohttp into the application environment, then add it to the project dependency file so fresh deployments receive it too.
An attribute error is different from No module named ‘aiohttp’ . It means Python found aiohttp, but the code expects an API that is missing, misspelled, or incompatible with the installed version.
Check these possibilities:
- The attribute name has the wrong capitalization. Python treats
appkeyandAppKeyas different names. - A library expects a different compatible
aiohttprelease. - A local file or folder named
aiohttpis shadowing the real package.
Use this command to see what file Python actually imported:
python -c "import aiohttp; print(aiohttp.__file__)"
If the result points into your project directory rather than the virtual environment’s package directory, rename the local aiohttp.py file or aiohttp folder, restart Python, and test the import again.
Confirm the Fix and Prevent It From Returning
Before considering the issue resolved, check all of the following:
- The interpreter path is the one your editor, test runner, or server uses.
- The direct
import aiohttptest succeeds. aiohttp.__file__points to the intended virtual environment or deployment environment.- The application starts or the failing test passes.
aiohttpis declared inrequirements.txt,pyproject.toml, or the project’s equivalent dependency file.- Docker images, CI jobs, and deployment environments rebuild from that declared dependency list.
For application code, treat a successful local install as a development convenience, not the permanent fix. The permanent fix is declaring the dependency so another developer, a fresh virtual environment, and production all install the same required package.
If the direct import works, run the original application again. If it still fails, capture the full traceback along with the Python executable path; those two details usually reveal the remaining environment or dependency mismatch.
Frequently Asked Questions
What is aiohttp in Python?
aiohttp is a third-party Python library for asynchronous HTTP requests, HTTP servers, and WebSockets. It is commonly used with asyncio when an application needs to make or serve network requests without blocking other asynchronous work.
Why does aiohttp show as installed but Python cannot import it?
aiohttp may be installed for a different Python interpreter than the one running your code. Check the executable with sys.executable, then install through that interpreter using the interpreter-bound pip form rather than relying on a separate global pip executable.
Why does VS Code say aiohttp is missing when my script runs?
VS Code’s selected interpreter may differ from the interpreter in the terminal where you installed the package. Select the project virtual environment with Python: Select Interpreter, open a new integrated terminal, and verify that the selected Python can import aiohttp.
How do I find the latest aiohttp version?
The latest version is the current release published for the aiohttp project, and it can change over time. Check the project’s release information or package index before pinning a version, then make sure the chosen version is compatible with the rest of your application’s dependencies.
Is aiohttp.web.AppKey the same error as no module named aiohttp?
No. A missing-module error means Python cannot locate the package at all. An AppKey or appkey attribute error means the package was imported, but the code and installed package version do not agree on the available API.
