Install & Compatibility
Where this runs
tested against v0.4.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
71MB installed
● package 71MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cache
✓ from django.core.cache import cache
✗ from django_valkey 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
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"))
Errors
Common errors & fixes
ImportError: cannot import name 'ValkeyCache' from 'django_valkey.cache'
You might have installed an old version (<0.1.0) or wrote the import path incorrectly.
fixEnsure you have django-valkey installed and use: from django_valkey.cache import ValkeyCache
django.core.cache.backends.base.InvalidCacheBackendError: Could not find backend 'django_valkey.cache.ValkeyCache'
The BACKEND path in CACHES settings is incorrect.
fixSet BACKEND to 'django_valkey.cache.ValkeyCache' and ensure django-valkey is installed.
redis.exceptions.ConnectionError: Error 111 connecting to 127.0.0.1:6379. Connection refused.
Valkey/Redis server is not running or unreachable.
fixStart a Valkey/Redis server: valkey-server (or redis-server) or check LOCATION in settings.
Upgrade
Version history
0.4.1latest on PyPI · released May 6, 2026
Audit
Dependencies
djangorequiredCore framework dependency.
valkeyrequiredPython client for Valkey (compatible with redis-py).
msgpackoptionalAlternative serializer (faster than default JSON).
pyzstdoptionalAlternative serializer for compression.
msgspecoptionalFast serialization format supported since 0.4.0.
hiredisoptionalC-based parser for improved performance.