Registry / http-networking / requests-cache

requests-cache

JSON →
library1.3.3pypypi✓ verified 27d ago

Requests-cache is a persistent HTTP cache that provides an easy way to get better performance with the popular Python `requests` library. It's particularly useful for web scraping, consuming REST APIs, or dealing with slow or rate-limited sites. It supports various storage backends like SQLite, Redis, MongoDB, DynamoDB, and the filesystem, offering flexible expiration strategies. The current version is 1.3.1, and it maintains an active release cadence.

pip install requests-cache
INSTALL
IMPORT
SIG · REQUESTS-CACHE
R
requests-cache
http-networkingpythonv1.3.3
Install
2.6s avg
Import
528ms
Disk
22MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.552s · 23.8MB
glibc
py 3.103.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.
fix
Access 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.
fix
Create 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.
fix
No 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.
fix
Prefer `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.
fix
Always 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.
fix
pip 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.
fix
import 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.
fix
pip install msgpack
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.
Agent activity
23 hits · last 30 days
node
20
OpenAI (training)
1
Resources
requests-cache — pip install requests-cache · libregistry