Redis with Django
Use Redis as the cache, session store, and channel layer for a Django application.
Django is a Python web framework. You can use Redis with Django as the cache, the session store, and the channel layer that connects WebSocket clients through Django Channels.
Requirements
| Dependency | Notes |
|---|---|
| Django | 4.0 or later for the built-in Redis cache backend |
| redis-py | Required by both cache backends |
| django-redis | Optional third-party cache backend |
| channels and channels-redis | Required for the channel layer |
The examples on this page were run with Django 6.1, django-redis 7.0, Channels 4.3, and channels-redis 4.3 against Redis 7.2.
You also need a running Redis server. You can run one locally with Redis Open Source, use Docker, or connect to Redis Cloud.
Cache data
Django has a built-in Redis cache backend, and the django-redis package provides a
second one. Both implement Django's standard cache API,
so the code that uses the cache is the same with either.
Use the built-in backend
Install redis-py, then point the CACHES setting at your server in settings.py:
pip install redis
CACHES = {
"default": {
"BACKEND": "django.core.cache.backends.redis.RedisCache",
"LOCATION": "redis://<your-redis-host>:6379",
"TIMEOUT": 300,
"KEY_PREFIX": "myapp",
}
}
Use django-redis
django-redis adds methods that the standard cache API doesn't have. Install it, then
use its backend:
pip install django-redis
CACHES = {
"default": {
"BACKEND": "django_redis.cache.RedisCache",
"LOCATION": "redis://<your-redis-host>:6379/0",
"OPTIONS": {"CLIENT_CLASS": "django_redis.client.DefaultClient"},
"KEY_PREFIX": "myapp",
}
}
With django-redis, the cache object also provides:
| Method | Use |
|---|---|
cache.ttl(key) |
Returns the remaining time to live (TTL) of a key in seconds. |
cache.delete_pattern("user:*") |
Deletes every key that matches a glob pattern and returns the number deleted. |
cache.lock(name, timeout=5) |
Returns a lock that you use with with, to coordinate work across processes. |
Read and write the cache
Use get_or_set() for the cache-aside
pattern. It returns the cached value, or calls your function and stores the result on
a miss:
from django.core.cache import cache
book = cache.get_or_set("book:1", load_book_from_database, timeout=30)
Django stores each entry under a key of the form <prefix>:<version>:<key>. With the
myapp prefix and the default version, the entry above is stored as myapp:1:book:1.
Values are serialized with pickle, so Redis stores them as strings, and the timeout
becomes the key's TTL.
Store sessions
Django can keep sessions in the cache, so with Redis as the cache they live in Redis.
Set the session engine in settings.py:
SESSION_ENGINE = "django.contrib.sessions.backends.cache"
SESSION_CACHE_ALIAS = "default"
SESSION_COOKIE_AGE = 900 # seconds
Django then stores each session as a cache entry such as
myapp:1:django.contrib.sessions.cache<session-key>, with a TTL equal to
SESSION_COOKIE_AGE.
A cache-based session lives only in Redis. If Redis evicts the key or loses its data,
the user's session ends. See the
Django session documentation
for the cached_db engine, which also writes sessions to your database.
See the session store use case for more about this pattern.
Broadcast messages with Channels
Django Channels adds WebSocket support to Django. Its Redis channel layer lets consumers running in different processes send messages to each other and to groups of clients. Install the packages:
pip install channels channels-redis
Configure the channel layer in settings.py:
CHANNEL_LAYERS = {
"default": {
"BACKEND": "channels_redis.core.RedisChannelLayer",
"CONFIG": {"hosts": [("<your-redis-host>", 6379)]},
}
}
The following consumer adds each connection to a group named after the chat room, and relays every message it receives to the whole group:
from channels.generic.websocket import AsyncWebsocketConsumer
class ChatConsumer(AsyncWebsocketConsumer):
async def connect(self):
self.room = self.scope["url_route"]["kwargs"]["room"]
await self.channel_layer.group_add(self.room, self.channel_name)
await self.accept()
async def disconnect(self, code):
await self.channel_layer.group_discard(self.room, self.channel_name)
async def receive(self, text_data):
await self.channel_layer.group_send(
self.room, {"type": "chat.message", "text": text_data}
)
async def chat_message(self, event):
await self.send(text_data=event["text"])
With two clients connected to the same room, a message sent by one arrives at both.
Channels keeps the group membership in Redis, under a key such as asgi:group:<room>.
See the pub/sub use case for other
ways to broadcast messages with Redis.