{"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,"search_vec":"'accord':35 'activ':44 'address':49 'aim':21 'algorithm':16 'bug':53 'cach':6,15,38,60,62 'cache-control':37 'cachecontrol':1,2 'compat':52 'control':39 'effici':30 'fix':54 'found':17 'frequent':47 'header':40 'http':5,33,59 'http-cach':58 'httplib2':19 'improv':57 'layer':7 'librari':12,42 'maintain':45 'make':23 'mimick':13 'perform':65 'persist':32 'popular':10 'provid':3 'python':50 'request':11,24,61 'respons':34 'safe':28 'serial':56 'session':25,66 'thread':27 'thread-saf':26 'updat':48 'version':51 'web':64 'web-perform':63","created_at":"2026-03-28T15:14:56.435761+00:00","updated_at":"2026-04-16T01:12:57.000550+00:00","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,"quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"0.14.4","cli_name":"","cli_version":null,"type":"library","homepage":"https://pypi.org/project/CacheControl/","github":"https://github.com/psf/cachecontrol","docs":null,"changelog":null,"pypi":"https://pypi.org/project/cachecontrol/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":"verified"}}