How to Install aiohttp in Python

aiohttp is a popular library for async HTTP in Python. It lets you build clients and servers that handle many requests at once.

In this guide, you will learn how to install aiohttp the right way. We will also cover common errors and a small working example.

What Is aiohttp?

aiohttp is an asynchronous HTTP client and server library. It is built on top of asyncio.

You use it to fetch web pages, call APIs, or build web servers. It is fast because it does not block while waiting for network responses.

Unlike requests, which is synchronous, aiohttp works with async and await. This makes it great for tasks that involve many network calls.

Requirements Before You Install

Before installing aiohttp, check a few basic things. This will save you time later.

• Python 3.8 or newer is recommended.
• pip should be installed and up to date.
• A virtual environment is strongly recommended.

You can check your Python version with this command.

python --version

The output should look like this.

Python 3.11.4

Step 1: Create a Virtual Environment

A virtual environment keeps your project dependencies separate. This avoids conflicts between projects.

Run the following command in your project folder.

python -m venv venv

Now activate the virtual environment.

On Windows:

venv\Scripts\activate

On macOS and Linux:

source venv/bin/activate

After activation, your terminal prompt will show the environment name. This means it is active.

Step 2: Install aiohttp with pip

Now install aiohttp using pip. This is the simplest and most common method.

pip install aiohttp

pip will download aiohttp and its dependencies. You should see a success message at the end.

Successfully installed aiohttp-3.9.1 aiosignal-1.3.1 attrs-23.1.0

That is it. aiohttp is now installed in your virtual environment.

Step 3: Verify the Installation

Always verify that the package works. This confirms the install was successful.

Run this command to check the version.

pip show aiohttp

The output will show details about the package.

Name: aiohttp
Version: 3.9.1
Summary: Async http client/server framework

You can also import it in Python to be sure.

import aiohttp

print(aiohttp.__version__)

The output prints the installed version.

3.9.1

Installing a Specific Version

Sometimes you need a specific version of aiohttp. This happens when a project requires an older release.

Use the == operator to pin the version.

pip install aiohttp==3.8.6

This installs exactly version 3.8.6. It is useful for keeping environments consistent.

Installing aiohttp on Windows

On Windows, aiohttp usually installs without issues. Modern pip uses prebuilt wheels.

If you see a build error, your Python version may be too old. Update Python and pip, then try again.

python -m pip install --upgrade pip
pip install aiohttp

This often fixes problems on Windows quickly.

Installing aiohttp on macOS and Linux

On macOS and Linux, aiohttp may need a C compiler. This is because some parts are built from source.

On Debian or Ubuntu, install the build tools first.

sudo apt install python3-dev build-essential

Then install aiohttp with pip.

pip install aiohttp

On macOS, make sure the Xcode command line tools are installed.

xcode-select --install

Common Installation Errors

Most aiohttp install problems are easy to fix. Here are the most common ones.

pip is not recognized

This means pip is not on your PATH. Use the module form instead.

python -m pip install aiohttp

Permission denied

This happens when you install globally without rights. Do not use sudo pip as a habit.

Instead, use a virtual environment. It avoids permission errors and keeps things clean.

ModuleNotFoundError after install

This error means Python cannot find aiohttp. It usually happens when you install in one environment and run in another.

Check that your virtual environment is active. Then confirm the install path.

which python
which pip

Both should point to the same virtual environment folder.

A Simple aiohttp Example

Let us test aiohttp with a small async program. It fetches a web page and prints the status code.

import aiohttp
import asyncio

async def fetch():
    # Open an async HTTP session
    async with aiohttp.ClientSession() as session:
        # Send a GET request to the URL
        async with session.get("https://example.com") as response:
            # Print the HTTP status code
            print("Status:", response.status)

# Run the async function
asyncio.run(fetch())

The output shows the status code of the request.

Status: 200

In this example, ClientSession manages connections. The session.get method sends the request. The asyncio.run function starts the event loop.

Always close sessions properly. The async with block handles that for you.

Using requirements.txt

For real projects, list aiohttp in a requirements file. This makes installs repeatable.

aiohttp==3.9.1

Then install everything at once.

pip install -r requirements.txt

This is the standard way to manage dependencies in Python projects.

Tips for a Clean Install

Follow these tips to avoid problems later.

• Always use a virtual environment.
• Keep pip updated with python -m pip install --upgrade pip.
• Pin versions in requirements.txt for team projects.
• Do not mix global and virtual installs.

These small habits prevent most installation headaches.

Conclusion

Installing aiohttp in Python is quick and simple. Use pip inside a virtual environment for the best results.

Verify the install, handle common errors, and test with a small async example. This confirms everything works.

Now you can build fast async clients and servers with aiohttp. Start with a simple request, then grow your project step by step.