User guide


Install with pip or easy_install:

pip install --upgrade requests-cache

or download latest version from version control:

git clone git://
cd requests-cache
python install


Version updates of requests, urllib3 or requests_cache itself can break existing cache database (see ). So if your code relies on cache, or is expensive in terms of time and traffic, please be sure to use something like virtualenv and pin your requirements.


There is two ways of using requests_cache:

Monkey-patching allows to add caching to existent program by adding just two lines:

Import requests_cache and call install_cache()

import requests
import requests_cache


And you can use requests, all responses will be cached transparently!

For example, following code will take only 1-2 seconds instead 10:

for i in range(10):

Cache can be configured with some options, such as cache filename, backend (sqlite, mongodb, redis, memory), expiration time, etc. E.g. cache stored in sqlite database (default format) named 'test_cache.sqlite' with expiration set to 300 seconds can be configured as:

requests_cache.install_cache('test_cache', backend='sqlite', expire_after=300)

See also

Full list of options can be found in requests_cache.install_cache() reference

Transparent caching is achieved by monkey-patching requests library It is possible to uninstall this patch with requests_cache.uninstall_cache().

Also, you can use requests_cache.disabled() context manager for temporary disabling caching:

with requests_cache.disabled():

If Response is taken from cache, from_cache attribute will be True:

>>> import requests
>>> import requests_cache
>>> requests_cache.install_cache()
>>> requests_cache.clear()
>>> r = requests.get('')
>>> r.from_cache
>>> r = requests.get('')
>>> r.from_cache

It can be used, for example, for request throttling with help of requests hook system:

import time
import requests
import requests_cache

def make_throttle_hook(timeout=1.0):
    Returns a response hook function which sleeps for `timeout` seconds if
    response is not cached
    def hook(response, *args, **kwargs):
        if not getattr(response, 'from_cache', False):
        return response
    return hook

if __name__ == '__main__':

    s = requests_cache.CachedSession()

See also


requests_cache prefetchs response content, be aware if your code uses streaming requests.

Request caching

If you want to cache on a per request basis, all requests support the expire_after keyword argument, which takes an expiration time in seconds:

requests.get('', expire_after=10)

Alternatively, expire_after accepts None, 'default', or a timedelta. None enables infinite caching, 'default' uses the expiry defined in install_cache(), and the timedelta is used as is.


Internally, numbers are converted to timedelta instances as well.


requests_cache designed to support different backends for persistent storage. By default it uses sqlite database. Type of storage can be selected with backend argument of install_cache().

List of available backends:

  • 'sqlite' - sqlite database (default)

  • 'memory' - not persistent, stores all data in Python dict in memory

  • 'mongodb' - (experimental) MongoDB database (pymongo < 3.0 required)

  • 'redis' - stores all data on a redis data store (redis required)

You can write your own and pass instance to install_cache() or CachedSession constructor. See Cache backends API documentation and sources.


If you are using cache with expire_after parameter set, responses are removed from the storage only when the same request is made. Since the store sizes can get out of control pretty quickly with expired items you can remove them using remove_expired_responses() or BaseCache.remove_old_entries(created_before).

expire_after = timedelta(hours=1)
# or
remove_old_entries.get_cache().remove_old_entries(datetime.utcnow() - expire_after)
# when used as session
session = CachedSession(..., expire_after=expire_after)
session.cache.remove_old_entries(datetime.utcnow() - expire_after)

For more information see API reference.

Usage with other libraries that modify requests.Session

This library works by patching requests.Session. Many other libraries out there do the same thing, making it difficult to combine them. For that case, a mixin class is provided, so you can create a custom class with behavior from multiple Session-modifying libraries:

from requests import Session
from requests_cache import CacheMixin
from some_other_lib import SomeOtherMixin

class CustomSession(CacheMixin, SomeOtherMixin ClientSession):
    """Session class with features from both requests-html and requests-cache"""

Example with requests-html:

import requests
from requests_cache import CacheMixin, install_cache
from requests_html import HTMLSession

class CachedHTMLSession(CacheMixin, HTMLSession):
    """Session with features from both CachedSession and HTMLSession"""

session = CachedHTMLSession()
r = session.get("")
print(r.from_cache, r.html.links)

Or, using the monkey-patch method:

r = requests.get("")
print(r.from_cache, r.html.links)

The same approach can be used with other libraries that subclass requests.Session.

Example with requests-mock:

import requests
from requests_mock import Mocker
from requests_cache import CachedSession

session = CachedSession()
with Mocker(session=session) as m:
    m.get('', text='mock_response')
    response = session.get('')