{"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,"search_vec":"'-6.0':23 '0.4.0':17 '3.10':20 '4.2':22 'advanc':26 'async':33 'backend':13,47 'bsd':41 'cach':12,44 'client':34 'cluster':31,49 'connect':36 'django':2,15,21,43 'django-valkey':1 'high':7 'high-perform':6 'includ':25 'licens':42 'modern':5 'msgpack':28 'msgspec':30 'perform':8 'python':19 'redi':11,46 'releas':38 'serial':27,48 'shard':37 'support':18,32 'valkey':3,9,45 'version':16 'zstd':29","created_at":"2026-05-01T08:08:40.360777+00:00","updated_at":"2026-05-01T08:08:40.360777+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.4.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/django-commons/django-valkey","docs":"https://django-valkey.readthedocs.io/en/latest/","changelog":null,"pypi":"https://pypi.org/project/django-valkey/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","web-framework","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-29","last_verified":"2026-06-29","next_check":"2026-07-29","install_tag":null}}