Install & Compatibility
Where this runs
tested against v0.3.7 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.624s · 27.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.9s · import 0.559s · 29MB
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AsyncCache
✓ from acachecontrol import AsyncCache
AsyncCacheControl
✓ from acachecontrol import AsyncCacheControl
This quickstart demonstrates how to use `acachecontrol` to cache HTTP GET requests made with `aiohttp`. The first request to `http://example.com` will fetch the content, and subsequent requests within the cache's validity period will be served from the cache without making a new network request to the origin server. The `from_cache` attribute on the response indicates if it was served from cache. You can configure `AsyncCache` with different backends if needed.
import asyncio
from acachecontrol import AsyncCache, AsyncCacheControl
async def main():
# Initialize AsyncCache, default configuration uses an in-memory dictionary
cache = AsyncCache()
# Use AsyncCacheControl to wrap an aiohttp ClientSession
async with AsyncCacheControl(cache=cache) as cached_session:
print("First request (should fetch):")
async with cached_session.get('http://example.com') as resp:
text_data = await resp.text()
print(f"Status: {resp.status}, From cache: {getattr(resp, 'from_cache', False)}")
# print(text_data[:100]) # Print first 100 chars for brevity
print("\nSecond request (should be cached):")
async with cached_session.get('http://example.com') as resp:
text_data = await resp.text()
print(f"Status: {resp.status}, From cache: {getattr(resp, 'from_cache', False)}")
# print(text_data[:100]) # Print first 100 chars for brevity
if __name__ == '__main__':
asyncio.run(main())
Debug
Known issues
breakingVersion 0.3.6 updated the minimum required `aiohttp` version to `>=3.10.2`. Using `acachecontrol` with older `aiohttp` versions may lead to compatibility issues or errors.fixEnsure `aiohttp` is installed with version `>=3.10.2`. Update `aiohttp` if an older version is present: `pip install --upgrade aiohttp`.
affects: <0.3.6
gotchaWhen implementing a custom cache backend for `AsyncCache`, it must fully adhere to the `OrderedDict` interface, including methods like `__contains__`, `__len__`, `__getitem__`, `__setitem__`, `get`, `pop`, `popitem`, and `move_to_end`. Incomplete implementations can cause unexpected runtime errors or incorrect caching behavior.fixRefer to the `CustomCacheBackend` example in the official documentation or GitHub README for a complete list of required methods and their expected behavior.
affects: All versions supporting custom backends
gotchaVersions of `acachecontrol` prior to `0.3.4` could fail if a `Cache-Control` header contained a `max-age` directive that was not a valid number. This would result in parsing errors and prevent caching.fixUpgrade to `acachecontrol>=0.3.4` to handle non-numeric `max-age` values gracefully. Additionally, ensure upstream services provide valid integer values for `max-age`.
affects: <0.3.4
gotchaA default request timeout issue was fixed in version `0.3.3`. Users of older versions might experience requests hanging or unexpectedly timing out under certain conditions.fixUpgrade to `acachecontrol>=0.3.3` to resolve this issue. Consider explicitly setting timeouts on `aiohttp.ClientSession` for fine-grained control if needed.
affects: <0.3.3
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'acachecontrol'
The 'acachecontrol' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install acachecontrol'.
ImportError: cannot import name 'AsyncCache' from 'acachecontrol'
The 'AsyncCache' class is not available in the 'acachecontrol' module.
fixEnsure you are using the correct import statement: 'from acachecontrol import AsyncCache, AsyncCacheControl'.
TypeError: 'NoneType' object is not subscriptable
Attempting to access elements of a 'None' object, possibly due to a failed request or uninitialized cache.
fixCheck if the response or cache object is 'None' before accessing its elements.
TypeError: AsyncCacheControl.__init__ missing 1 required positional argument: 'cache'
The AsyncCacheControl class requires an instance of AsyncCache (or a compatible cache object) to be passed via the 'cache' keyword argument during initialization.
fixfrom acachecontrol import AsyncCache, AsyncCacheControl
cache_instance = AsyncCache()
session = AsyncCacheControl(cache=cache_instance)
NameError: name 'AsyncCacheControl' is not defined
The AsyncCacheControl class was used without being imported first from the 'acachecontrol' library.
fixfrom acachecontrol import AsyncCacheControl
Upgrade
Version history
0.3.7latest on PyPI · released Jan 26, 2026
Audit
Dependencies
aiohttprequiredCore dependency for asynchronous HTTP requests, updated to >=3.10.2 in v0.3.6.