django-redis: a Redis cache and session backend for Django

The problem django-redis solves inside a Django project

Django ships with a cache framework and a small set of backends: local memory, filesystem, database and memcached. Redis is not among them. The framework gives you a single API (cache.set, cache.get, cache.delete, cache.get_many) and expects a backend class to implement it. django-redis is that class. It registers django_redis.cache.RedisCache, which satisfies Django's BaseCache interface on top of redis-py, so existing code that calls the cache API keeps working after you change one setting.

The second job is sessions. Django can store sessions in any cache backend through django.contrib.sessions.backends.cache, and the README points out that you get session storage "without installing any additional backends". That matters for deployments where session data should live outside the application process, for example behind a load balancer with several Django workers.

The intended audience is a Django developer who already operates a Redis server. The README states Redis server 2.8+ as the floor. If you do not run Redis and have no reason to, this package adds an external dependency for no gain over Django's built-in backends.

How the backend talks to Redis: redis-py URLs and pluggable parts

Connection strings use redis-py's native URL notation rather than a host/port pair. Three schemes are supported: redis:// for a normal TCP socket, rediss:// for a TLS-wrapped TCP socket, and unix:// for a Unix domain socket. The database number can appear either as a querystring option (redis://localhost?db=0) or, with the redis:// scheme, as the path (redis://localhost/0).

Authentication has a precedence rule worth reading twice. With Redis ACLs you put the username and password in the connection string or in OPTIONS under the keys USERNAME and PASSWORD, and the README states plainly that values in the connection string have precedence. Mixing the two forms is allowed as long as the connection string carries no password at all, even an empty one.

Around that core the package exposes four extension points: clients, parsers, serializers and compressors. The default client is documented as supporting primary/secondary setups, which is the reason a project would pick this over hand-rolling a redis-py connection in a settings file. Serialization defaults to pickle, using pickle.DEFAULT_PROTOCOL so that upgrades across Python versions stay compatible; PICKLE_VERSION in OPTIONS overrides it, and -1 selects the highest protocol available. Compression is off until you name a class: django_redis.compressors.zlib.ZlibCompressor, django_redis.compressors.lzma.LzmaCompressor, and an lz4 compressor that the README notes requires the lz4 library. The pyproject file lists optional extras for lz4, msgpack and pyzstd, so those paths are installable rather than theoretical.

Installing django-redis and making a first cache call

The README gives one install command. Run it in the environment that runs your Django project.

python -m pip install django-redis

Then point Django's cache at Redis. This is the example from the README, using database 1 on localhost. The LOCATION value is a redis-py URL, not a host and port pair.

CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379/1",
    }
}

After that, ordinary cache calls go through Redis with no further code. To store sessions in the same cache, the README gives these two settings.

SESSION_ENGINE = "django.contrib.sessions.backends.cache"
SESSION_CACHE_ALIAS = "default"

The package also exposes the raw connection for cases the cache API does not cover. The README shows this import and a flushall call in a test tearDown, which is the documented way to clear data between tests.

from django_redis import get_redis_connection

def tearDown(self):
    get_redis_connection("default").flushall()

Be careful with that call outside tests. flushall empties the whole Redis database, not just the keys Django wrote, and the README presents it in a testing context only.

Where django-redis is the wrong tool

The package is a cache backend, and a cache backend inherits the failure mode of the thing it caches into. If the Redis server is unreachable, a cache read fails rather than falling back to a slower path. The README does not document a circuit breaker, a local fallback cache, or a degraded mode. Django's cache API is written to treat a cache as optional, but that contract only holds if the backend swallows errors, and nothing in the supplied documentation says this one does. Treat a Redis outage as an application outage until you verify otherwise.

Redis is also not a database, and using it as the session store makes that concrete. Session data in a cache backend is subject to eviction. If your Redis instance runs with a maxmemory policy that evicts keys, or if someone runs flushall, sessions disappear and users are logged out. The README says django-redis is "used in production in several projects as cache and session storage", which describes adoption, not a durability guarantee.

Serialization is the third boundary. The default is pickle. Pickle deserializes arbitrary objects, so anything that can write to your Redis instance can, in principle, influence what your application unpickles. If the cache is reachable by more than your own application, this is the setting to reconsider before anything else. The package supports other serializers through the pluggable serializer option, and the README does not pick one for you.

Finally, this is not a task queue. Several of the related searches pair django-redis with Celery, and the two are separate: Celery uses Redis as a broker and result store through its own transport, not through this cache backend. Installing django-redis does not configure Celery.

django-redis compared with memcached and with plain redis-py

The closest comparison is Django's built-in memcached backend. The difference is in the data model, not the API. Memcached stores opaque bytes with a size limit per item and no persistence; Redis stores typed values and can persist to disk. Redis also gives you the operations the README exposes beyond the cache interface: get_redis_connection hands back a client where you can call lists, sets, sorted sets, pub/sub and Lua scripts. If all you need is key/value caching with a small item size, memcached is simpler to operate and has no persistence to reason about. If you want the cache and a data structure store in the same process, Redis is the one that does both, and django-redis is the bridge.

The other comparison is django-redis against redis-py used directly. redis-py is the client library; django-redis depends on it and is declared as redis>=4.0.2 in pyproject. Using redis-py directly means you own connection pooling, key naming, serialization and integration with Django's cache and session frameworks yourself. Using django-redis means you get those conventions already made, at the cost of accepting its choices: pickle by default, no compression by default, and a configuration surface expressed as OPTIONS keys such as SOCKET_TIMEOUT, SOCKET_CONNECT_TIMEOUT and PICKLE_VERSION. The timeout pair is worth setting explicitly, since the README distinguishes the connect timeout from the read and write timeout and neither has a documented default here.

Maintenance, versions and what the licence covers

The repository is not archived and the last push was on 2026-09-21, three days before this writing. Release 7.0.0 landed on 2026-06-02, after 6.0.0 on 2025-06-17 and 5.4.0 on 2023-10-01. The gap between 5.4.0 and 6.0.0 is roughly twenty months, so the release cadence is uneven and a version bump can carry a long interval of accumulated change. The CHANGELOG.rst file at the repository root and the changelog.d/ directory are where that change is recorded; the README does not document a deprecation policy or a rollback procedure for a bad upgrade.

Version floors are strict and worth checking before you start. pyproject declares requires-python >=3.10 and dependencies of Django>=5.2,<7.0 and redis>=4.0.2, with typing_extensions>=4.12 on Python 3.12 and below. The Django ceiling of <7.0 means a future Django 7 release will need a new django-redis version. Django 5.2 is a recent floor, so projects on older Django lines cannot use 7.0.0 without upgrading Django first.

On licensing: the README calls the project BSD licensed and pyproject declares license = "BSD-3-Clause" under the SPDX expression form, while the repository metadata shows NOASSERTION. Those are not contradictory so much as differently precise, and the LICENSE file in the repository root is the text that governs. That is a statement about what the files say, not legal advice; if the distinction matters to your organisation, read LICENSE rather than this paragraph.

Editorial conclusion

Adopt django-redis if you already run Redis and want Django's cache API plus session storage on top of it without writing your own backend; skip it if you need a cache that survives a Redis outage, since this backend does not provide one. Before committing, verify your Django and Python versions against the declared floors (Django 5.2+, Python 3.10+), decide whether the default pickle serializer is acceptable for your data, and confirm how you will flush stale keys after a deploy, because django-redis inherits Django's cache versioning rather than adding its own.

Frequently asked questions

Official sources

1. Issues
2. jazzband/django-redis on GitHub
3. README
4. Releases