django-redis

6.0.0 · active · verified Thu Apr 09

django-redis is a full-featured Redis cache backend for Django, providing robust integration with Redis as Django's caching system. The current version is 6.0.0, released in June 2025, and it typically sees several updates per year, following Django's release cycle.

Warnings

gotcha When using `redis-py` version 5.0 or newer with `hiredis` installed, you must explicitly set `PARSER_CLASS` in `CACHES OPTIONS` to `redis.connection.HiredisParser` for `hiredis` to be utilized correctly. Failure to do so may result in `hiredis` not being used, impacting performance.
Fix: Ensure `pip install hiredis` is run, then add `"PARSER_CLASS": "redis.connection.HiredisParser"` to the `OPTIONS` dictionary in your `CACHES` configuration.
breaking Always verify `django-redis` compatibility with your specific Django version. New `django-redis` versions often introduce support for newer Django versions, while dropping support for older ones. For example, Django 4.x support was added in `django-redis` 5.3.0.
Fix: Consult the `django-redis` GitHub releases or documentation (e.g., `requires_python` field) for the supported Django versions before upgrading either library.
gotcha By default, `django-redis` uses Python's `pickle` module for serialization. This can pose security risks if untrusted data is deserialized, and limits interoperability with non-Python clients or services that expect common formats like JSON.
Fix: For improved security and interoperability, configure a different serializer, such as JSON, by setting `"SERIALIZER": "django_redis.serializers.json.JSONSerializer"` in your `CACHES OPTIONS`.
gotcha Incorrect `LOCATION` string format or inaccessible Redis server can lead to `ConnectionError` or `TimeoutError`. The format is crucial (e.g., `redis://host:port/db_number`).
Fix: Double-check the Redis URI format in your `settings.py` (e.g., `redis://127.0.0.1:6379/1`). Ensure the Redis server is running and accessible from the Django application's host and port.

Install

pip install django-redis Base installation
pip install django-redis hiredis With hiredis for performance

Imports

RedisCache
```
from django_redis.cache import RedisCache
```
While 'DefaultClient' is a component, 'RedisCache' is the backend class itself, specified in Django settings.py.

Quickstart

To get started, configure the `CACHES` setting in your Django project's `settings.py` file to use `django_redis.cache.RedisCache` as the backend. Specify the Redis connection string in `LOCATION` and any desired `OPTIONS` like client class or serializer. Once configured, you can interact with the cache using Django's standard `django.core.cache.cache` object.

# settings.py
CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379/1",
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.DefaultClient",
            # For redis-py >= 5.0 with hiredis:
            # "PARSER_CLASS": "redis.connection.HiredisParser",
            "SERIALIZER": "django_redis.serializers.json.JSONSerializer" # Example of changing serializer
        }
    }
}

# app_name/views.py or similar
from django.core.cache import cache

def my_view(request):
    value = cache.get('my_key')
    if value is None:
        value = 'data_from_db'
        cache.set('my_key', value, timeout=300) # Cache for 5 minutes
    return f"<h1>Cached Value: {value}</h1>"

view raw JSON →