Skip to content

django-cachex

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

PyPI version Python versions Django versions

What's in the box

A drop-in replacement for Django's built-in Redis cache, plus:

  • One package for both Valkey and Redis, default and Sentinel and Cluster.
  • Sync and async support sharing one configuration. The async cache works from sync code too.
  • 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) behind 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.

Requirements

  • Python 3.14+ (free-threaded supported)
  • Django 6.0+
  • valkey-py 6.1+ (redis-py 6.0+ also supported)
  • 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)

Quick Start

Install with pip:

pip install django-cachex[valkey-py]

Configure as cache backend:

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

Enable the admin interface (optional):

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

Acknowledgments

This project was inspired by django-redis and Django's official Redis cache backend. Some utility code for serializers and compressors is derived from django-redis, licensed under BSD-3-Clause. The admin functionality 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.

See also django-valkey and dj-cache-panel for related projects with similar goals.

License

MIT License. See LICENSE for details.