{"id":5839,"library":"aiohttp-client-cache","title":"aiohttp-client-cache","description":"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.","status":"active","version":"0.14.3","language":"en","source_language":"en","source_url":"https://github.com/requests-cache/aiohttp-client-cache","tags":["aiohttp","cache","http client","async","persistence","requests-cache"],"install":[{"cmd":"pip install aiohttp-client-cache","lang":"bash","label":"Base installation"},{"cmd":"pip install aiohttp-client-cache[all]","lang":"bash","label":"With all backend dependencies"}],"dependencies":[{"reason":"Core library for which caching is provided.","package":"aiohttp"},{"reason":"Required for SQLiteBackend.","package":"aiosqlite","optional":true},{"reason":"Required for MongoDBBackend.","package":"motor","optional":true},{"reason":"Required for RedisBackend.","package":"redis-py","optional":true}],"imports":[{"symbol":"CachedSession","correct":"from aiohttp_client_cache import CachedSession"},{"symbol":"SQLiteBackend","correct":"from aiohttp_client_cache import SQLiteBackend"},{"note":"Use CachedSession for caching behavior; ClientSession is the uncached aiohttp client.","wrong":"from aiohttp import ClientSession","symbol":"ClientSession (when caching is desired)","correct":"from aiohttp_client_cache import CachedSession"},{"note":"aiohttp-cache is for aiohttp web server caching, not client requests. Use aiohttp-client-cache for client-side caching.","wrong":"import aiohttp_cache","symbol":"aiohttp-cache (for client-side caching)","correct":"from aiohttp_client_cache import CachedSession"}],"quickstart":{"code":"import asyncio\nfrom aiohttp_client_cache import CachedSession, SQLiteBackend\n\nasync def main():\n    # Initialize CachedSession with a SQLite backend\n    # 'demo_cache' will be the filename for the SQLite database\n    async with CachedSession(cache=SQLiteBackend('demo_cache')) as session:\n        print(\"First request (will be slow...\")\n        response = await session.get('http://httpbin.org/delay/1')\n        print(f\"Response from cache: {response.from_cache}, Status: {response.status}\")\n\n        print(\"Second request (should be fast...\")\n        response = await session.get('http://httpbin.org/delay/1')\n        print(f\"Response from cache: {response.from_cache}, Status: {response.status}\")\n\nif __name__ == '__main__':\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"fix":"Clear existing cache files or databases after updating, or simply allow the cache to repopulate.","message":"Upgrading 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.","severity":"breaking","affected_versions":">=0.12.0"},{"fix":"Upgrade your Python environment to 3.9 or higher.","message":"Minimum Python version required is 3.9+ since v0.13.0. Earlier Python versions are no longer supported.","severity":"breaking","affected_versions":">=0.13.0"},{"fix":"Refer to the documentation on 'Cache Expiration' and 'Cache-Control' to understand how different expiration settings interact and ensure desired caching behavior.","message":"Caching 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.","severity":"gotcha","affected_versions":"All"},{"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'))`.","message":"By 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.","severity":"gotcha","affected_versions":"All"},{"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))`.","message":"By 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.","severity":"gotcha","affected_versions":"All"},{"fix":"Pin your dependency to a specific minor version and thoroughly test when upgrading to newer minor or patch versions.","message":"The library is an 'early work in progress' and breaking changes should be expected until a 1.0 release.","severity":"gotcha","affected_versions":"<1.0.0"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}