{"id":1456,"library":"django-redis","title":"django-redis","description":"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.","status":"active","version":"6.0.0","language":"python","source_language":"en","source_url":"https://github.com/jazzband/django-redis","tags":["django","redis","cache","backend","web"],"install":[{"cmd":"pip install django-redis","lang":"bash","label":"Base installation"},{"cmd":"pip install django-redis hiredis","lang":"bash","label":"With hiredis for performance"}],"dependencies":[{"reason":"Core Redis client library utilized by django-redis.","package":"redis","optional":false},{"reason":"Optional C-based parser for redis-py, significantly improving performance.","package":"hiredis","optional":true}],"imports":[{"note":"While 'DefaultClient' is a component, 'RedisCache' is the backend class itself, specified in Django settings.py.","wrong":"from django_redis.client import DefaultClient","symbol":"RedisCache","correct":"from django_redis.cache import RedisCache"}],"quickstart":{"code":"# settings.py\nCACHES = {\n    \"default\": {\n        \"BACKEND\": \"django_redis.cache.RedisCache\",\n        \"LOCATION\": \"redis://127.0.0.1:6379/1\",\n        \"OPTIONS\": {\n            \"CLIENT_CLASS\": \"django_redis.client.DefaultClient\",\n            # For redis-py >= 5.0 with hiredis:\n            # \"PARSER_CLASS\": \"redis.connection.HiredisParser\",\n            \"SERIALIZER\": \"django_redis.serializers.json.JSONSerializer\" # Example of changing serializer\n        }\n    }\n}\n\n# app_name/views.py or similar\nfrom django.core.cache import cache\n\ndef my_view(request):\n    value = cache.get('my_key')\n    if value is None:\n        value = 'data_from_db'\n        cache.set('my_key', value, timeout=300) # Cache for 5 minutes\n    return f\"<h1>Cached Value: {value}</h1>\"","lang":"python","description":"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."},"warnings":[{"fix":"Ensure `pip install hiredis` is run, then add `\"PARSER_CLASS\": \"redis.connection.HiredisParser\"` to the `OPTIONS` dictionary in your `CACHES` configuration.","message":"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.","severity":"gotcha","affected_versions":"5.4.0+ with redis-py >= 5.0"},{"fix":"Consult the `django-redis` GitHub releases or documentation (e.g., `requires_python` field) for the supported Django versions before upgrading either library.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'2025':35 '6.0.0':31 'backend':14,52 'cach':13,25,51 'current':28 'cycl':48 'django':2,5,16,23,45,49 'django-redi':1,4 'featur':11 'follow':44 'full':10 'full-featur':9 'integr':19 'june':34 'per':42 'provid':17 'redi':3,6,12,21,50 'releas':32,47 'robust':18 'see':39 'sever':40 'system':26 'typic':38 'updat':41 'version':29 'web':53 'year':43","created_at":"2026-04-09T03:48:42.949433+00:00","updated_at":"2026-04-16T14:34:17.266404+00:00","problems":[{"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.","cause":"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).","error":"ModuleNotFoundError: No module named 'django_redis'"},{"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.","cause":"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).","error":"redis.exceptions.ConnectionError: Error 111 connecting to 0.0.0.0:6379. Connection refused."},{"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.","cause":"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.","error":"django.core.exceptions.ImproperlyConfigured: Requested setting CACHES, but settings are not configured."},{"fix":"Correct the `BACKEND` setting in your `CACHES` configuration from `'django.core.cache.backends.redis.RedisCache'` to `'django_redis.cache.RedisCache'`.","cause":"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`.","error":"AbstractConnection.init() got an unexpected keyword argument 'CLIENT_CLASS'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"7.0.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/jazzband/django-redis","docs":null,"changelog":null,"pypi":"https://pypi.org/project/django-redis/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","web-framework","aws"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"verified"}}