---
id: aioresponses
version: "0.7.9"
license: unclear
license_treatment: permissive
maintenance: active
---

# aioresponses — Mock out requests made by ClientSession from aiohttp package

License: permissive · Maintenance: active · Downloads: 9.3M/mo

## What it is and what it does

aioresponses is a testing helper that intercepts and mocks HTTP requests made by aiohttp's ClientSession, letting you test asynchronous code without hitting real servers. It works as a decorator or context manager and lets you specify mock responses by URL, including status codes, JSON payloads, headers, and exceptions. You can also use regex patterns to match URLs, repeat responses for retry testing, simulate redirects, or pass through to real servers selectively.

The package fills a gap in the async testing ecosystem—while synchronous HTTP libraries have many mocking options, aioresponses makes it straightforward to test async code that uses aiohttp. It depends on aiohttp and packaging, both common in Python projects. The library is actively maintained and has been stable since its early releases.

Use it for:

- Test async functions that call external APIs without making real network requests
- Verify retry logic by mocking the same URL to return different status codes in sequence
- Mock JSON API responses to test data parsing in async code
- Simulate HTTP errors and exceptions to test error handling in async workflows
- Test redirect handling by mocking Location headers with 3xx status codes

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Mocks HTTP requests made by aiohttp's ClientSession for testing asynchronous code, supporting GET, POST, PUT, PATCH, DELETE, and OPTIONS methods with customizable status codes, bodies, headers, and JSON payloads.

Yes. aioresponses is a focused, well-maintained tool for a common testing need in async Python. It has no known vulnerabilities, low install friction, a permissive license, and active development. Install it if you write tests for code using aiohttp.

## Install

pip install aioresponses
uv add aioresponses
poetry add aioresponses

## Installing aioresponses

Before you install: Low friction install with just two runtime dependencies (packaging and aiohttp). Actively maintained with a recent release; repository shows steady activity and moderate community engagement.

License in practice: Permissive license allows unrestricted use in commercial and open-source projects without copyleft obligations.

Quickstart:

pip install aioresponses

from aioresponses import aioresponses
import aiohttp
import asyncio

@aioresponses()
def test_example(mocked):
    mocked.get('http://example.com', status=200, body='test')
    session = aiohttp.ClientSession()
    resp = asyncio.run(session.get('http://example.com'))
    assert resp.status == 200

Requires Python 3.10+ and aiohttp>=3.8,<4.0

Verify before relying:

- Whether the package supports Python 3.14 in practice (listed as classifier but may be aspirational)

## Package facts

- License: not declared (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: active
- Downloads: 9.3M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

mock aiohttp requests, async http testing, aiohttp test fixtures, fake async web requests, aiohttp response mocking, asyncio http mocking, test aiohttp client, async-testing, http-mocking

[View on SkillFed](https://skillfed.io/packages/aioresponses) · [View on PyPI](https://pypi.org/project/aioresponses/)