Install & Compatibility
Where this runs
tested against v1.3.3 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.552s · 23.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.6s · import 0.504s · 24MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CachedSession
✓ from requests_cache import CachedSession
✗ from requests_cache.core import CachedSession
Official documentation recommends importing directly from the top-level `requests_cache` package.
install_cache
✓ from requests_cache import install_cache
The most common and recommended way to use `requests-cache` is by creating a `CachedSession` instance, which acts as a direct replacement for `requests.Session`. This example demonstrates making a request, observing it being cached, and then retrieving it from the cache instantly on a subsequent call. It also shows how to clear the cache.
import requests_cache
import requests
# Use CachedSession as a drop-in replacement for requests.Session
session = requests_cache.CachedSession('demo_cache', expire_after=3600)
# Make a request; it will be cached
response1 = session.get('https://httpbin.org/delay/1')
print(f"First request (from cache: {response1.from_cache}): {response1.status_code}")
# Make the same request again; it will be loaded from cache instantly
response2 = session.get('https://httpbin.org/delay/1')
print(f"Second request (from cache: {response2.from_cache}): {response2.status_code}")
# Example for global patching (less recommended for complex apps)
# requests_cache.install_cache('global_cache', expire_after=3600)
# response3 = requests.get('https://httpbin.org/delay/1')
# print(f"Third request (from cache: {getattr(response3, 'from_cache', False)}): {response3.status_code}")
# Clear the cache
session.cache.clear()
print("Cache cleared.")
Debug
Known issues
breakingPrior to version 1.0, cache settings could sometimes be modified directly on `CachedSession` or `BaseCache`. As of 1.0, settings can only be accessed and modified via `CachedSession.settings` after initialization.fixAccess and modify cache settings exclusively through `session.settings` attribute, e.g., `session.settings.expire_after = 7200`.
affects: >=1.0.0
breakingFor users of the DynamoDB backend, the table structure changed in version 1.0. Upgrading to 1.0 requires creating a new DynamoDB table, as existing tables are incompatible.fixCreate a new DynamoDB table when upgrading if you are using the DynamoDB backend. Refer to the DynamoDB backend documentation for details.
affects: >=1.0.0
breakingResponses cached with `requests-cache` versions prior to 0.6.0 are invalid due to serialization format changes. These old responses will be treated as expired and automatically re-fetched.fixNo direct fix needed; old entries will be re-fetched. Users can manually clear the cache (`session.cache.clear()`) or convert old cache formats if supported by specific minor versions (check historical changelogs).
affects: 0.6.0 to current
gotchaThe global patching method (`requests_cache.install_cache()`) has limitations and can lead to unexpected behavior, especially in multi-threaded/multiprocess applications, when used with other `requests`-patching libraries, or in larger applications where cache behavior might not be obvious across modules. Using `CachedSession` is generally recommended.fixPrefer `requests_cache.CachedSession` over `requests_cache.install_cache()` for explicit control over caching behavior.
affects: All versions
gotchaThe core `requests` library does not natively cache HTTP responses. Users expecting caching behavior without `requests-cache` (or similar) will not get it. When using `requests-cache`, not explicitly calling `clear()` or misconfiguring `expire_after` are common mistakes for managing data freshness.fixAlways use `requests_cache.CachedSession` or `requests_cache.install_cache()` for HTTP response caching. Explicitly manage cache entries using `session.cache.clear()` or `expire_after` settings for desired data freshness.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'requests_cache'
The 'requests-cache' package has not been installed in your current Python environment.
fixpip install requests-cache
AttributeError: module 'requests_cache' has no attribute 'install_cache'
The `install_cache()` function was deprecated and removed in requests-cache versions 0.6.0 and later, favoring the `CachedSession` API.
fiximport requests_cache; session = requests_cache.CachedSession('demo_cache'); response = session.get('https://httpbin.org/get') ModuleNotFoundError: No module named 'msgpack'
The `msgpack` library, an optional dependency required for the `fast_pickle` serializer (used for optimal SQLite caching), is not installed.
Upgrade
Version history
1.3.3latest on PyPI · released Jul 3, 2026
Audit
Dependencies
requestsrequiredCore dependency for HTTP requests functionality.
cattrsrequiredRequired for optimized serialization.
appdirsrequiredUsed for cross-platform user cache directory management.
itsdangerousoptionalOptional but recommended for more secure serialization.