django-valkey

0.4.0 verified Fri May 01 auth: no python

A modern, high-performance Valkey (and Redis) cache backend for Django. Version 0.4.0 supports Python >=3.10, Django 4.2-6.0, and includes advanced serialization (msgpack, zstd, msgspec), cluster support, async clients, and connection sharding. Released under the BSD license.

pip install django-valkey

Common errors

error ImportError: cannot import name 'ValkeyCache' from 'django_valkey.cache' ↓

cause You might have installed an old version (<0.1.0) or wrote the import path incorrectly.

fix

Ensure you have django-valkey installed and use: from django_valkey.cache import ValkeyCache

error django.core.cache.backends.base.InvalidCacheBackendError: Could not find backend 'django_valkey.cache.ValkeyCache' ↓

cause The BACKEND path in CACHES settings is incorrect.

fix

Set BACKEND to 'django_valkey.cache.ValkeyCache' and ensure django-valkey is installed.

error redis.exceptions.ConnectionError: Error 111 connecting to 127.0.0.1:6379. Connection refused. ↓

cause Valkey/Redis server is not running or unreachable.

fix

Start a Valkey/Redis server: valkey-server (or redis-server) or check LOCATION in settings.

Warnings

breaking In version 0.2.1, floats are no longer serialized to support atomic float operations. If your code relied on serialization of floats (e.g., storing float as string), you may need to adjust. ↓

fix None needed unless you were reading serialized floats from older versions; ensure compatibility.

breaking In version 0.3.0, `make_key`, `make_pattern`, `encode`, and `decode` became module-level functions (not just backend methods). If you were overriding them in a custom backend, update your code. ↓

fix Use `from django_valkey import make_key` instead of `self.make_key`.

gotcha The backend class is `django_valkey.cache.ValkeyCache`, not `django_valkey.cache.RedisCache` (the old name from django-redis). Using wrong backend name will cause ImportError. ↓

fix Use `'BACKEND': 'django_valkey.cache.ValkeyCache'` in CACHES settings.

deprecated The old `BaseConnectionPool` class was renamed to `BaseConnectionFactory` in version 0.1.4. Using the old name will trigger a deprecation warning and may be removed. ↓

fix Use `BaseConnectionFactory` instead of `BaseConnectionPool`.

Install

pip install django-valkey[msgpack]

pip install django-valkey[zstd]

pip install django-valkey[hiredis]

Imports

cache
wrong
```
from django_valkey import cache
```
correct
```
from django.core.cache import cache
```
django-valkey integrates as a Django cache backend; you import the standard Django cache object.

get_valkey_connection

from django_valkey import get_valkey_connection

Quickstart

Configure django-valkey as your default cache backend.

# In settings.py:
CACHES = {
    "default": {
        "BACKEND": "django_valkey.cache.ValkeyCache",
        "LOCATION": "valkey://127.0.0.1:6379/1",
        "OPTIONS": {
            "CLIENT_CLASS": "django_valkey.client.DefaultClient",
        }
    }
}

# In your code:
from django.core.cache import cache
cache.set("my_key", "hello world", timeout=60)
print(cache.get("my_key"))