Registry / http-networking / aiohttp-client-cache

aiohttp-client-cache

JSON →
library0.14.3pypypi✓ verified 21d ago

aiohttp-client-cache is an async persistent cache for aiohttp client requests, based on requests-cache. It provides a CachedSession that acts as a drop-in replacement for `aiohttp.ClientSession`, offering various configurable storage backends and cache expiration strategies. The current version is 0.14.3, and it receives regular updates for bug fixes and compatibility.

pip install aiohttp-client-cache
INSTALL
IMPORT
SIG · AIOHTTP-CLIENT-CAC
A
aiohttp-client-cache
http-networkingpythonv0.14.3
Install
6.5s avg
Import
1216ms
Disk
77MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.14.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 1.246s · 74.6MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 6.5s · import 1.185s · 78MB
77MB installed
● package 77MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

CachedSession
from aiohttp_client_cache import CachedSession
SQLiteBackend
from aiohttp_client_cache import SQLiteBackend
ClientSession (when caching is desired)
from aiohttp_client_cache import CachedSession
from aiohttp import ClientSession
Use CachedSession for caching behavior; ClientSession is the uncached aiohttp client.
aiohttp-cache (for client-side caching)
from aiohttp_client_cache import CachedSession
import aiohttp_cache
aiohttp-cache is for aiohttp web server caching, not client requests. Use aiohttp-client-cache for client-side caching.

This example demonstrates basic usage of CachedSession with a SQLite backend. The first request to 'httpbin.org/delay/1' will fetch the data and store it in 'demo_cache.sqlite'. Subsequent requests to the same URL will retrieve the response instantly from the cache. The `response.from_cache` attribute indicates if the response was served from the cache.

import asyncio from aiohttp_client_cache import CachedSession, SQLiteBackend async def main(): # Initialize CachedSession with a SQLite backend # 'demo_cache' will be the filename for the SQLite database async with CachedSession(cache=SQLiteBackend('demo_cache')) as session: print("First request (will be slow...") response = await session.get('http://httpbin.org/delay/1') print(f"Response from cache: {response.from_cache}, Status: {response.status}") print("Second request (should be fast...") response = await session.get('http://httpbin.org/delay/1') print(f"Response from cache: {response.from_cache}, Status: {response.status}") if __name__ == '__main__': asyncio.run(main())
Debug
Known issues
breakingUpgrading to v0.12.0 or later may invalidate previously cached data due to internal changes. Users should clear their cache or be prepared for a temporary loss of cached responses.
fix
Clear existing cache files or databases after updating, or simply allow the cache to repopulate.
affects: >=0.12.0
breakingMinimum Python version required is 3.9+ since v0.13.0. Earlier Python versions are no longer supported.
fix
Upgrade your Python environment to 3.9 or higher.
affects: >=0.13.0
gotchaCaching behavior is determined by a precedence order: Cache-Control request headers > Cache-Control response headers > per-request expiration > per-URL expiration > per-session expiration. This can lead to unexpected caching if not understood.
fix
Refer to the documentation on 'Cache Expiration' and 'Cache-Control' to understand how different expiration settings interact and ensure desired caching behavior.
affects: All
gotchaBy default, `CachedSession` without a specified `cache` backend will use a non-persistent, in-memory cache. Data will be lost when the session or application closes.
fix
Always explicitly configure a persistent backend (e.g., `SQLiteBackend`, `RedisBackend`) when you need data to persist across application runs. Example: `CachedSession(cache=SQLiteBackend('my_cache.sqlite'))`.
affects: All
gotchaBy default, only `GET` and `HEAD` HTTP methods and `200` status codes are cached. Requests using other methods (like `POST`) or responses with other status codes will not be cached unless explicitly configured.
fix
Use `allowed_methods` and `allowed_codes` parameters in your backend configuration to cache additional methods or status codes. Example: `SQLiteBackend(allowed_methods=('GET', 'POST'), allowed_codes=(200, 404))`.
affects: All
gotchaThe library is an 'early work in progress' and breaking changes should be expected until a 1.0 release.
fix
Pin your dependency to a specific minor version and thoroughly test when upgrading to newer minor or patch versions.
affects: <1.0.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aiohttp_client_cache'
This error occurs when the 'aiohttp-client-cache' package is not installed in your Python environment.
fix
Install the package using pip: 'pip install aiohttp-client-cache'.
AttributeError: module 'aiohttp' has no attribute 'ClientSession'
This error can occur if there's a circular import or if the 'aiohttp' module is not properly installed.
fix
Ensure that 'aiohttp' is installed correctly and check for circular imports in your code. Also, avoid naming your script 'aiohttp.py' to prevent conflicts.
ImportError: cannot import name 'CachedSession' from 'aiohttp_client_cache'
This error occurs when attempting to import 'CachedSession' from 'aiohttp_client_cache' without the package being installed or due to an incorrect import statement.
fix
Ensure that 'aiohttp-client-cache' is installed and use the correct import statement: 'from aiohttp_client_cache import CachedSession'.
TypeError: 'NoneType' object is not callable
This error can occur if 'CachedSession' is not properly initialized or if there's an issue with the cache backend configuration.
fix
Verify that 'CachedSession' is initialized correctly with a valid cache backend, for example: 'session = CachedSession(cache=SQLiteBackend('demo_cache'))'.
ValueError: Invalid backend: 'redis'
This error occurs when specifying a cache backend that is not installed or supported.
fix
Ensure that the required backend dependencies are installed. For Redis, install the package with the Redis extras: 'pip install aiohttp-client-cache[redis]'.
Upgrade
Version history
0.14.3latest on PyPI · released Jan 7, 2026
Audit
Dependencies
aiohttprequiredCore library for which caching is provided.
aiosqliteoptionalRequired for SQLiteBackend.
motoroptionalRequired for MongoDBBackend.
redis-pyoptionalRequired for RedisBackend.
Agent activity
39 hits · last 30 days
node
30
OpenAI (training)
2
Amazon
1
Resources
aiohttp-client-cache — pip install aiohttp-client-cache · libregistry