{"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":"python","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-05-23T10:49:38.139Z","next_check":"2026-07-13T00:00:00.000Z","problems":[{"fix":"Install the package using pip: 'pip install aiohttp-client-cache'.","cause":"This error occurs when the 'aiohttp-client-cache' package is not installed in your Python environment.","error":"ModuleNotFoundError: No module named 'aiohttp_client_cache'"},{"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.","cause":"This error can occur if there's a circular import or if the 'aiohttp' module is not properly installed.","error":"AttributeError: module 'aiohttp' has no attribute 'ClientSession'"},{"fix":"Ensure that 'aiohttp-client-cache' is installed and use the correct import statement: 'from aiohttp_client_cache import CachedSession'.","cause":"This error occurs when attempting to import 'CachedSession' from 'aiohttp_client_cache' without the package being installed or due to an incorrect import statement.","error":"ImportError: cannot import name 'CachedSession' from 'aiohttp_client_cache'"},{"fix":"Verify that 'CachedSession' is initialized correctly with a valid cache backend, for example: 'session = CachedSession(cache=SQLiteBackend('demo_cache'))'.","cause":"This error can occur if 'CachedSession' is not properly initialized or if there's an issue with the cache backend configuration.","error":"TypeError: 'NoneType' object is not callable"},{"fix":"Ensure that the required backend dependencies are installed. For Redis, install the package with the Redis extras: 'pip install aiohttp-client-cache[redis]'.","cause":"This error occurs when specifying a cache backend that is not installed or supported.","error":"ValueError: Invalid backend: 'redis'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.14.3","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/requests-cache/aiohttp-client-cache","docs":"https://aiohttp-client-cache.readthedocs.io","changelog":null,"pypi":"https://pypi.org/project/aiohttp-client-cache/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","database"],"base_url":null,"auth_type":null,"install_checks":{"last_tested":"2026-05-23","tag":null,"tag_description":null,"installed_version":"0.14.3","pypi_latest":"0.14.3","is_stale":false,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"aiohttp-client-cache","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.67,"mem_mb":17.3,"disk_size":"27.6M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":"sdist","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":1.43,"mem_mb":30.6,"disk_size":"73.4M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"aiohttp-client-cache","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":4.7,"import_time_s":0.47,"mem_mb":17.3,"disk_size":"30M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":9.8,"import_time_s":1.15,"mem_mb":30.6,"disk_size":"77M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"aiohttp-client-cache","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.86,"mem_mb":19,"disk_size":"30.3M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":"sdist","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":1.75,"mem_mb":34.9,"disk_size":"79.8M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"aiohttp-client-cache","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":4,"import_time_s":0.74,"mem_mb":19,"disk_size":"33M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":8.4,"import_time_s":1.62,"mem_mb":35,"disk_size":"85M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"aiohttp-client-cache","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":1.05,"mem_mb":19.1,"disk_size":"22.1M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":"sdist","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":1.82,"mem_mb":34.3,"disk_size":"70.9M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"aiohttp-client-cache","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":3,"import_time_s":0.96,"mem_mb":19.1,"disk_size":"24M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":6.7,"import_time_s":1.91,"mem_mb":34.4,"disk_size":"76M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"aiohttp-client-cache","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":1.09,"mem_mb":20.1,"disk_size":"21.5M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":"sdist","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":1.82,"mem_mb":35.6,"disk_size":"70.3M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"aiohttp-client-cache","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":3.1,"import_time_s":0.96,"mem_mb":20.1,"disk_size":"24M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":6.5,"import_time_s":1.79,"mem_mb":35.7,"disk_size":"77M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"aiohttp-client-cache","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.62,"mem_mb":16.9,"disk_size":"27.8M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":"sdist","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":1.28,"mem_mb":30.3,"disk_size":"72.8M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"aiohttp-client-cache","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":5.3,"import_time_s":0.61,"mem_mb":16.9,"disk_size":"30M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":11.3,"import_time_s":1.4,"mem_mb":30.3,"disk_size":"76M"}]},"_links":{"self":"https://checklist.day/api/registry/aiohttp-client-cache","v1":"https://checklist.day/v1/registry/aiohttp-client-cache","v1_install":"https://checklist.day/v1/registry/aiohttp-client-cache/install","v1_imports":"https://checklist.day/v1/registry/aiohttp-client-cache/imports","v1_compatibility":"https://checklist.day/v1/registry/aiohttp-client-cache/compatibility","v1_quickstart":"https://checklist.day/v1/registry/aiohttp-client-cache/quickstart","docs":"https://checklist.day/docs"}}