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.

Note:

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.

More information

RATE THIS PAGE
Back to top ↑