django-cachex

Valkey and Redis cache backend for Django, with a Django admin UI for cache inspection.

Installation

pip install django-cachex[valkey-py]

Quick Start

CACHES = {
    "default": {
        "BACKEND": "django_cachex.cache.ValkeyCache",
        "LOCATION": "valkey://127.0.0.1:6379/1",
    }
}

What's in the box

• One package for both Valkey and Redis, default and Sentinel and Cluster.
• Sync and async are first-class. The async cache also works from sync code.
• Hash, list, set, sorted set, and stream operations on the cache object.
• TTL and pattern helpers (ttl(), expire(), keys(), delete_pattern()).
• Distributed locks: cache.lock().
• Weighted semaphores: cache.semaphore() for budget-based concurrency gating (counting and weighted, in-process and distributed).
• Lua scripting with automatic key prefixing and value encoding/decoding.
• Pluggable serializers (Pickle, JSON, MsgPack, ormsgpack, orjson) and compressors (Zlib, Gzip, LZ4, LZMA, Zstandard), each with fallback chains for safe migrations.
• Cache stampede prevention (TTL-based XFetch).
• Two composite backends: StreamCache (cross-pod stream-synchronized in-memory cache) and TieredCache (L1/L2 with TTL propagation).
• Django LocMemCache and DatabaseCache extensions with the same data-structure ops and admin support.
• Optional Rust I/O driver (PyO3 + tokio + redis-rs) under the same RespCache API. Free-threaded CPython (3.14t) supported. Experimental.
• Optional valkey-glide adapter: Valkey's official Rust-cored client, exposed as ValkeyGlideCache. Experimental.
• Django admin UI for browsing keys, inspecting values, editing, and flushing. See below.

Cache Admin

Add django_cachex.admin to your INSTALLED_APPS to enable the cache admin interface:

INSTALLED_APPS = [
    # ...
    "django_cachex.admin",
]

Browse all configured caches, search and filter keys by type, and manage values directly:

Features:

• Browse all configured cache backends (Valkey, Redis, LocMemCache, DatabaseCache, and more)
• Search keys with wildcard patterns (user:*, *:session)
• Filter by key type (string, list, set, hash, zset, stream)
• View and edit values with type-specific operations
• Inspect and modify TTL
• View server info and memory statistics
• Flush caches

Documentation

Full documentation at oliverhaas.github.io/django-cachex

Requirements

• Python 3.14+ (free-threaded supported)
• Django 6.0+
• valkey-py 6.1+ or redis-py 6.0+
• Valkey 7.0+ or Redis 6.0+ on the server (the admin's compare-and-swap edits use SET ... KEEPTTL, which lands in Redis 6.0)

The Rust I/O driver is optional and experimental: interfaces and behavior may still change, and it has seen less production testing than the redis-py/valkey-py paths. To opt in, install with the redis-rs extra (pip install django-cachex[redis-rs]); this pulls in the django-cachex-redis-rs companion package. Prebuilt wheels are published for Linux x86_64, Linux aarch64, macOS arm64, and Windows amd64, on both cp314 and cp314t (free-threaded). Without the extra, the RedisRsCache backends are unavailable but everything else works.

The valkey-glide adapter is also optional and experimental, with the same caveats. Install with the valkey-glide extra (pip install django-cachex[valkey-glide]) to enable ValkeyGlideCache; it pulls in valkey-glide-sync and valkey-glide, the official Rust-cored Valkey client. cp314 GIL only; no free-threaded wheels yet. Cluster is supported via ValkeyGlideClusterCache; Sentinel is not currently exposed (valkey-glide itself does not ship a Sentinel client).

Acknowledgments

This project started from django-redis and Django's official Redis cache backend. Some serializer and compressor utility code is derived from django-redis, licensed under BSD-3-Clause. The admin UI was inspired by django-redisboard.

The Rust I/O driver and async bridge are heavily inspired by, and in places directly adapted from, django-vcache (MIT, by David Burke / GlitchTip). The fork-safe tokio runtime, the RedisRsAwaitable deferred-loop-binding pattern, and the multiplexed-connection design all originate there.

I also want to mention django-valkey and dj-cache-panel, which I never really used, but are newer and interesting efforts of similar goals as this package has.

License

MIT