Registry / database / django-redis

django-redis

JSON →
library7.0.0pypypi✓ verified 26d ago

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.

databaseweb-frameworkaws
pip install django-redis
github ↗package ↗
INSTALL
IMPORT
SIG · DJANGO-REDIS
D
django-redis
databasepythonv7.0.0
Install
4.1s avg
Import
256ms
Disk
72MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v7.0.0 · 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.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.263s · 72.6MB
glibc
py 3.10–3.910 runs
installs and imports cleanly · install 4.1s · import 0.248s · 73MB
72MB installed
● package 72MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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>"
Debug
Known issues
gotchaWhen 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.
affects: 5.4.0+ with redis-py >= 5.0
breakingAlways 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.
affects: All versions
gotchaBy 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`.
affects: All versions
gotchaIncorrect `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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'django_redis'
The `django-redis` package is not installed in the Python environment where the Django application is running, or the environment is not correctly configured (e.g., in a Docker container or virtual environment).
fix
Install the package using `pip install django-redis`. If using a `requirements.txt` file, ensure `django-redis` is listed and the environment (e.g., Docker image) is rebuilt.
redis.exceptions.ConnectionError: Error 111 connecting to 0.0.0.0:6379. Connection refused.
The Django application cannot establish a connection with the Redis server. This is commonly due to the Redis server not running, incorrect host/port in `CACHES` settings, firewall blocking the connection, or misconfiguration in containerized environments (e.g., Docker networking).
fix
Verify that the Redis server is running and accessible at the specified host and port. In `settings.py`, ensure the `LOCATION` in your `CACHES` configuration is correct (e.g., `redis://127.0.0.1:6379` for local or `redis://redis:6379` if using Docker Compose service named 'redis'). Check firewall rules and Docker network configurations.
django.core.exceptions.ImproperlyConfigured: Requested setting CACHES, but settings are not configured.
This error occurs when Django's `CACHES` setting is accessed before Django's settings are fully loaded, or if the `CACHES` dictionary is not defined in your `settings.py` file. This can happen when importing `cache` from `django.core.cache` directly at the module level before `DJANGO_SETTINGS_MODULE` is set or `settings.configure()` is called.
fix
Ensure that `CACHES` is properly defined in your `settings.py` file. If running standalone scripts or in the Django shell, ensure the `DJANGO_SETTINGS_MODULE` environment variable is set or `django.setup()` is called before accessing any Django settings. Avoid importing `cache` at the top level of modules that are loaded very early in the Django startup process.
AbstractConnection.init() got an unexpected keyword argument 'CLIENT_CLASS'
This error typically indicates that the `BACKEND` path in your `settings.CACHES` configuration is incorrectly set to Django's built-in `django.core.cache.backends.redis.RedisCache` instead of `django_redis.cache.RedisCache` when attempting to use `django-redis`-specific `OPTIONS` like `CLIENT_CLASS`.
fix
Correct the `BACKEND` setting in your `CACHES` configuration from `'django.core.cache.backends.redis.RedisCache'` to `'django_redis.cache.RedisCache'`.
Upgrade
Version history
7.0.0latest on PyPI · released Jun 2, 2026
Audit
Dependencies
redisrequiredCore Redis client library utilized by django-redis.
hiredisoptionalOptional C-based parser for redis-py, significantly improving performance.
Agent activity
19 hits · last 30 days
node
16
Amazon
1
Resources
githubhttps://github.com/jazzband/django-redis ↗
packagehttps://pypi.org/project/django-redis/ ↗
django-redis — pip install django-redis · libregistry