Build status Documentation Status Codecov PyPI Conda PyPI - Python Versions PyPI - Format

aiohttp-client-cache is an async persistent cache for aiohttp client requests, based on requests-cache.


  • Ease of use: Use as a drop-in replacement for aiohttp.ClientSession

  • Customization: Works out of the box with little to no config, but with plenty of options available for customizing cache expiration and other behavior

  • Persistence: Includes several storage backends: SQLite, DynamoDB, MongoDB, DragonflyDB and Redis.


First, install with pip (python 3.8+ required):

pip install aiohttp-client-cache[all]

Note: Adding [all] will install optional dependencies for all supported backends. When adding this library to your application, you can include only the dependencies you actually need; see individual backend docs and pyproject.toml for details.

Basic Usage#

Next, use aiohttp_client_cache.CachedSession in place of aiohttp.ClientSession. To briefly demonstrate how to use it:

Replace this:

from aiohttp import ClientSession

async with ClientSession() as session:
    await session.get('')

With this:

from aiohttp_client_cache import CachedSession, SQLiteBackend

async with CachedSession(cache=SQLiteBackend('demo_cache')) as session:
    await session.get('')

The URL in this example adds a delay of 1 second, simulating a slow or rate-limited website. With caching, the response will be fetched once, saved to demo_cache.sqlite, and subsequent requests will return the cached response near-instantly.


Several options are available to customize caching behavior. This example demonstrates a few of them:

# fmt: off
from aiohttp_client_cache import SQLiteBackend

cache = SQLiteBackend(
    cache_name='~/.cache/aiohttp-requests.db',  # For SQLite, this will be used as the filename
    expire_after=60*60,                         # By default, cached responses expire in an hour
    urls_expire_after={'*': -1}, # Requests for any subdomain on this site will never expire
    allowed_codes=(200, 418),                   # Cache responses with these status codes
    allowed_methods=['GET', 'POST'],            # Cache requests with these HTTP methods
    include_headers=True,                       # Cache requests with different headers separately
    ignored_params=['auth_token'],              # Keep using the cached response even if this param changes
    timeout=2.5,                                # Connection timeout for SQLite backend

More Info#

To learn more, see:


If there is a feature you want, if you’ve discovered a bug, or if you have other general feedback, please create an issue for it!


Project Info#