{"id":469,"library":"cachecontrol","title":"CacheControl","description":"CacheControl provides an HTTP caching layer for the popular `requests` library, mimicking the caching algorithms found in `httplib2`. It aims to make `requests` sessions thread-safe and efficient by persisting HTTP responses according to cache-control headers. The library is actively maintained, with frequent updates addressing Python version compatibility, bug fixes, and serialization improvements.","status":"active","version":"0.14.4","language":"python","source_language":"en","source_url":"https://github.com/psf/cachecontrol","tags":["http-caching","requests","cache","web-performance","session"],"install":[{"cmd":"pip install cachecontrol","lang":"bash","label":"Base installation"},{"cmd":"pip install cachecontrol[filecache]","lang":"bash","label":"With FileCache support (includes msgpack and filelock)"}],"dependencies":[{"reason":"Core integration; CacheControl extends requests.Session objects.","package":"requests"},{"reason":"Optional dependency for FileCache and other disk-based caches for efficient serialization, specifically msgpack < 2.0.0.","package":"msgpack","optional":true},{"reason":"Optional dependency for FileCache and SeparateBodyFileCache to prevent race conditions during file access.","package":"filelock","optional":true}],"imports":[{"note":"The primary class to wrap a requests.Session for caching.","symbol":"CacheControl","correct":"from cachecontrol import CacheControl"},{"note":"Used for persisting cache entries to the filesystem, requires `cachecontrol[filecache]`.","symbol":"FileCache","correct":"from cachecontrol.caches.file_cache import FileCache"},{"note":"Alternative way to apply caching via requests' Transport Adapters, often used with `session.mount()`.","symbol":"CacheControlAdapter","correct":"from cachecontrol.adapter import CacheControlAdapter"}],"quickstart":{"code":"import requests\nfrom cachecontrol import CacheControl\nfrom cachecontrol.caches.file_cache import FileCache\n\n# Create a standard requests session\nsess = requests.Session()\n\n# Wrap the session with CacheControl using a FileCache for persistent storage\n# Replace '.web_cache' with your desired cache directory\ncached_sess = CacheControl(sess, cache=FileCache('.web_cache'))\n\n# Make a request - the response will be cached if HTTP headers allow\nresponse = cached_sess.get('https://httpbin.org/cache/60')\nprint(f\"First request status: {response.status_code}\")\nprint(f\"From cache (should be False): {getattr(response, 'from_cache', False)}\")\n\n# Make the same request again - it should now be served from cache\nresponse = cached_sess.get('https://httpbin.org/cache/60')\nprint(f\"Second request status: {response.status_code}\")\nprint(f\"From cache (should be True): {getattr(response, 'from_cache', False)}\")\n\n# Clean up the cache directory (optional for a real app)\n# import shutil\n# shutil.rmtree('.web_cache', ignore_errors=True)\n","lang":"python","description":"This quickstart demonstrates how to set up `CacheControl` with `requests` using a persistent `FileCache`. The first `GET` request will fetch data from the network and cache it. Subsequent requests to the same URL, if cacheable, will be served from the local cache."},"warnings":[{"fix":"Upgrade your Python interpreter to version 3.10 or newer, or pin `cachecontrol` to an older compatible version.","message":"Python 3.8 support was dropped in v0.14.3. Python versions older than 3.10 are no longer officially supported as of v0.14.4. Ensure your environment meets the `>=3.10` requirement.","severity":"breaking","affected_versions":">=0.14.3"},{"fix":"Clear any existing cache directories or stores before upgrading to v0.13.1 or newer if you suspect they were created with very old versions of the library.","message":"Serialization format changes: Version `0.13.1` removed support for older serialization formats (v1 and v2). Caches created with very old versions of `cachecontrol` (before `msgpack` was introduced around v0.12.0) will be unreadable after upgrading.","severity":"breaking","affected_versions":">=0.13.1"},{"fix":"Check your project's dependency tree for `msgpack` conflicts. You may need to use a virtual environment or dependency resolver like `pip-tools` or `Poetry` to manage versions. Consider using a different cache backend if `msgpack` conflicts are unavoidable.","message":"The `msgpack` dependency has a version constraint (`<2.0.0`) since `v0.14.0`. If other libraries in your project require `msgpack >= 2.0.0`, you might encounter dependency conflicts.","severity":"gotcha","affected_versions":">=0.14.0"},{"fix":"Upgrade `cachecontrol` to at least `0.13.0` (or `0.12.13` if staying on the `0.12.x` line) to ensure compatibility with `urllib3 2.0` and newer `requests` versions.","message":"Older versions of `cachecontrol` (pre-`v0.12.13`/`v0.13.0`) might have compatibility issues with `requests` sessions using `urllib3 2.0+`, leading to `IncompleteRead` errors.","severity":"gotcha","affected_versions":"<0.12.13 || <0.13.0"},{"fix":"Upgrade to `cachecontrol` version `0.14.2` or newer, especially if your application involves high concurrency or multiple processes accessing the same `FileCache` directory.","message":"A race condition when overwriting cache entries was fixed in `v0.14.2`. Concurrent writes to the same cache file could lead to corruption in earlier versions.","severity":"gotcha","affected_versions":"<0.14.2"},{"fix":"Consider using `SeparateBodyFileCache` (available from `v0.12.11`) instead of `FileCache` or `DictCache` for memory-intensive caching scenarios, and ensure you have `filelock` installed.","message":"Memory usage with `DictCache` or older `FileCache` implementations can be excessive for large binary responses. `SeparateBodyFileCache` was introduced for better memory efficiency by streaming large bodies.","severity":"gotcha","affected_versions":"<0.12.11"}],"env_vars":null,"last_verified":"2026-05-12T14:04:10.955Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Reinstalling or upgrading `pip` often resolves this. You can try `python -m ensurepip` or `python -m pip install --upgrade pip --force-reinstall`.","cause":"This error typically occurs when your `pip` installation is corrupted or an internal dependency (like `cachecontrol`, which `pip` uses) is missing or cannot be found within `pip`'s vendorized packages. It's not usually a direct issue with the `cachecontrol` library itself but rather with `pip`.","error":"ModuleNotFoundError: No module named 'pip._vendor.cachecontrol'"},{"fix":"Ensure you are interacting with a `CacheControl` wrapped session and accessing the cache control headers appropriately, typically through HTTP response headers or methods provided by `CacheControl`, not directly as an attribute on a raw response dictionary. If attempting to check `Cache-Control` HTTP headers, access `response.headers['Cache-Control']` on a standard `requests` response.","cause":"This error arises when you attempt to access a `.cache_control` attribute on a dictionary object, usually when trying to get caching information directly from a `requests` response object or a generic dictionary instead of the `CacheControl` wrapped session or its response object, which exposes such attributes.","error":"AttributeError: 'dict' object has no attribute 'cache_control'"},{"fix":"Initialize `CacheControl` with a persistent cache backend, such as `FileCache`.\n```python\nimport requests\nfrom cachecontrol import CacheControl\nfrom cachecontrol.caches import FileCache\n\nsess = requests.session()\ncached_sess = CacheControl(sess, cache=FileCache('.web_cache'))\nresponse = cached_sess.get('https://example.com')\n```","cause":"By default, `CacheControl` uses an in-memory cache, meaning the cache is cleared when the program exits. If you expect caching to persist across different runs of your application, you need to explicitly configure a persistent cache backend (e.g., `FileCache`).","error":"CacheControl not caching (requests are not being cached as expected)"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.58,"mem_mb":9.8,"disk_size":"22.3M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"filecache","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.57,"mem_mb":9.8,"disk_size":"22.6M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.41,"mem_mb":9.8,"disk_size":"23M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"filecache","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.4,"mem_mb":9.8,"disk_size":"23M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.77,"mem_mb":11,"disk_size":"24.5M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"filecache","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.77,"mem_mb":11,"disk_size":"24.7M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.64,"mem_mb":11,"disk_size":"25M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"filecache","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.63,"mem_mb":11,"disk_size":"26M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.71,"mem_mb":11.4,"disk_size":"16.3M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"filecache","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.7,"mem_mb":11.4,"disk_size":"16.5M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.67,"mem_mb":11.4,"disk_size":"17M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"filecache","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.71,"mem_mb":11.4,"disk_size":"17M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.68,"mem_mb":11.8,"disk_size":"15.9M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"filecache","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.69,"mem_mb":11.8,"disk_size":"16.2M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.67,"mem_mb":11.8,"disk_size":"17M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"filecache","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.68,"mem_mb":11.8,"disk_size":"17M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.53,"mem_mb":9.5,"disk_size":"21.6M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"filecache","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.56,"mem_mb":9.5,"disk_size":"21.7M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.52,"mem_mb":9.5,"disk_size":"22M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"filecache","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.47,"mem_mb":9.5,"disk_size":"23M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}