{"id":23609,"library":"django-valkey","title":"django-valkey","description":"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.","status":"active","version":"0.4.0","language":"python","source_language":"en","source_url":"https://github.com/django-commons/django-valkey","tags":["django","cache","valkey","redis","backend","serialization","cluster"],"install":[{"cmd":"pip install django-valkey","lang":"bash","label":"Basic install"},{"cmd":"pip install django-valkey[msgpack]","lang":"bash","label":"With msgpack support"},{"cmd":"pip install django-valkey[zstd]","lang":"bash","label":"With zstd support"},{"cmd":"pip install django-valkey[hiredis]","lang":"bash","label":"With hiredis C parser"}],"dependencies":[{"reason":"Core framework dependency.","package":"django","optional":false},{"reason":"Python client for Valkey (compatible with redis-py).","package":"valkey","optional":false},{"reason":"Alternative serializer (faster than default JSON).","package":"msgpack","optional":true},{"reason":"Alternative serializer for compression.","package":"pyzstd","optional":true},{"reason":"Fast serialization format supported since 0.4.0.","package":"msgspec","optional":true},{"reason":"C-based parser for improved performance.","package":"hiredis","optional":true}],"imports":[{"note":"django-valkey integrates as a Django cache backend; you import the standard Django cache object.","wrong":"from django_valkey import cache","symbol":"cache","correct":"from django.core.cache import cache"},{"note":"","wrong":"","symbol":"get_valkey_connection","correct":"from django_valkey import get_valkey_connection"}],"quickstart":{"code":"# In settings.py:\nCACHES = {\n    \"default\": {\n        \"BACKEND\": \"django_valkey.cache.ValkeyCache\",\n        \"LOCATION\": \"valkey://127.0.0.1:6379/1\",\n        \"OPTIONS\": {\n            \"CLIENT_CLASS\": \"django_valkey.client.DefaultClient\",\n        }\n    }\n}\n\n# In your code:\nfrom django.core.cache import cache\ncache.set(\"my_key\", \"hello world\", timeout=60)\nprint(cache.get(\"my_key\"))","lang":"python","description":"Configure django-valkey as your default cache backend."},"warnings":[{"fix":"None needed unless you were reading serialized floats from older versions; ensure compatibility.","message":"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.","severity":"breaking","affected_versions":">=0.2.1"},{"fix":"Use `from django_valkey import make_key` instead of `self.make_key`.","message":"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.","severity":"breaking","affected_versions":"0.3.0+"},{"fix":"Use `'BACKEND': 'django_valkey.cache.ValkeyCache'` in CACHES settings.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Use `BaseConnectionFactory` instead of `BaseConnectionPool`.","message":"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.","severity":"deprecated","affected_versions":">=0.1.4"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Ensure you have django-valkey installed and use: from django_valkey.cache import ValkeyCache","cause":"You might have installed an old version (<0.1.0) or wrote the import path incorrectly.","error":"ImportError: cannot import name 'ValkeyCache' from 'django_valkey.cache'"},{"fix":"Set BACKEND to 'django_valkey.cache.ValkeyCache' and ensure django-valkey is installed.","cause":"The BACKEND path in CACHES settings is incorrect.","error":"django.core.cache.backends.base.InvalidCacheBackendError: Could not find backend 'django_valkey.cache.ValkeyCache'"},{"fix":"Start a Valkey/Redis server: valkey-server (or redis-server) or check LOCATION in settings.","cause":"Valkey/Redis server is not running or unreachable.","error":"redis.exceptions.ConnectionError: Error 111 connecting to 127.0.0.1:6379. Connection refused."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}