Requests Cache

1.3.1 verified Tue May 12 auth: no python install: verified

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

Common errors

error ModuleNotFoundError: No module named 'requests_cache' ↓

cause The 'requests-cache' package has not been installed in your current Python environment.

fix

pip install requests-cache

error AttributeError: module 'requests_cache' has no attribute 'install_cache' ↓

cause 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')

error ModuleNotFoundError: No module named 'msgpack' ↓

cause The `msgpack` library, an optional dependency required for the `fast_pickle` serializer (used for optimal SQLite caching), is not installed.

fix

pip install msgpack

Warnings

breaking Prior 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`.

breaking For 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.

breaking Responses 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).

gotcha The 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.

gotcha The 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.

Install compatibility verified last tested: 2026-05-12 v1.3.2 (up to date)

python os / libc status wheel install import disk mem side effects

3.10 alpine (musl) wheel - 0.74s 23.8M 13.7M clean

3.10 alpine (musl) - - 0.80s 23.7M 13.6M -

3.10 slim (glibc) wheel 2.5s 0.52s 24M 13.7M clean

3.10 slim (glibc) - - 0.56s 24M 13.6M -

3.11 alpine (musl) wheel - 0.96s 26.2M 15.0M clean

3.11 alpine (musl) - - 1.08s 26.0M 14.8M -

3.11 slim (glibc) wheel 2.5s 0.83s 27M 15.0M clean

3.11 slim (glibc) - - 0.83s 27M 14.8M -

3.12 alpine (musl) wheel - 0.81s 17.8M 14.6M clean

3.12 alpine (musl) - - 0.91s 17.7M 14.5M -

3.12 slim (glibc) wheel 2.3s 0.84s 18M 14.6M clean

3.12 slim (glibc) - - 0.88s 18M 14.5M -

3.13 alpine (musl) wheel - 0.80s 17.6M 15.4M clean

3.13 alpine (musl) - - 0.90s 17.4M 15.3M -

3.13 slim (glibc) wheel 2.3s 0.81s 18M 15.4M clean

3.13 slim (glibc) - - 0.89s 18M 15.3M -

3.9 alpine (musl) wheel - 0.69s 23.0M 13.3M clean

3.9 alpine (musl) - - 0.74s 23.0M 13.2M -

3.9 slim (glibc) wheel 2.9s 0.61s 24M 13.3M clean

3.9 slim (glibc) - - 0.67s 23M 13.2M -

Imports

CachedSession
wrong
```
from requests_cache.core import CachedSession
```
correct
```
from requests_cache import CachedSession
```
Official documentation recommends importing directly from the top-level `requests_cache` package.

install_cache

from requests_cache import install_cache

Quickstart last tested: 2026-04-24

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.")