Skip to content

About

Cache extensions for django, including better Valkey/Redis backends and an admin interface.

Topics

Resources

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

django-cachex

PyPI version Python versions CI

Valkey and Redis cache backend for Django, with a Django admin UI for cache inspection. Full documentation at oliverhaas.github.io/django-cachex.

Quick Start

pip install django-cachex[valkey-py]
CACHES = {
    "default": {
        "BACKEND": "django_cachex.cache.ValkeyCache",
        "LOCATION": "valkey://127.0.0.1:6379/1",
    }
}

Features

  • One package for Valkey and Redis, standalone, Sentinel and Cluster.
  • Sync and async methods on every cache (get() and aget()), from one alias and one configuration.
  • Hash, list, set, sorted set and stream operations, and TTL and pattern helpers (ttl(), expire(), keys(), delete_pattern()).
  • Distributed locks with cache.lock().
  • Counting and weighted semaphores with cache.semaphore(), in-process or distributed.
  • Lua scripting with eval_script(), with optional key-prefixing and encoding hooks.
  • Pluggable serializers (Pickle, JSON, MsgPack, ormsgpack, orjson) and compressors (Zlib, Gzip, LZ4, LZMA, Zstandard), each with a fallback chain to migrate between formats.
  • Cache stampede prevention (TTL-based XFetch).
  • Client tracking, one option that keeps local copies of the values each process reads, kept current by the server's CLIENT TRACKING.
  • An opt-in ORM cache, django_cachex.orm, that caches ORM query results per table and invalidates them on every write.
  • LocMemCache and DatabaseCache extensions with the hash, list, set and sorted set operations, ttl()/expire()/persist(), key patterns and admin support, but no streams, locks, pipelines or Lua.
  • Experimental ValkeyGlideCache and ValkeyGlideClusterCache backends on valkey-glide, Valkey's official client with a Rust core.
  • S3Cache, which stores large values in an S3 Express One Zone or S3 Standard bucket, with parallel get_many() and set_many(). See S3 Cache.

Cache Admin

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

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

The admin lists every configured cache, finds keys by wildcard pattern and type, and edits values and TTLs. It also shows server info and memory statistics, and with CACHEX_ADMIN = {"ALLOW_FLUSH": True} it flushes caches.

Cache list Key list Key detail

Requirements

  • Python 3.14+, including the free-threaded build (3.14t). On 3.14t, importing hiredis or libvalkey re-enables the GIL with a RuntimeWarning, unless you run with PYTHON_GIL=0 (or -Xgil=0).
  • Django 6.0 to 6.x (Django>=6,<7)
  • valkey-py 6.1 to 6.x (valkey>=6.1,<7) or redis-py 7.2 to 8.x (redis>=7.2,<9)
  • Valkey 7.2+ or Redis 6.2+ on the server. Installation lists the methods that need a newer server.
  • valkey-glide 2.5 to 2.x (the valkey-glide extra) for the glide backends. They need the cp314 GIL build and have no Sentinel variant.
  • obstore 0.12 (the s3 extra) for S3Cache.

Acknowledgments

This project started from django-redis and Django's official Redis cache backend. The admin UI was inspired by django-redisboard. The ORM cache is derived from django-cachalot 2.9.1 by Bertrand Bordage. The ASGI benchmark follows the shape of django-vcache's bench_compare.py (MIT, by David Burke / GlitchTip).

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

License

MIT, see LICENSE, except for two parts under BSD-3-Clause:

  • The ORM cache, django_cachex/orm/, derived from django-cachalot. See django_cachex/orm/LICENSE.
  • Parts of django_cachex/serializers/, django_cachex/compressors/ and django_cachex/exceptions.py, derived from django-redis (Copyright (c) 2011-2016 Andrey Antukh). Each derived file says so in its header. See LICENSE.django-redis.

About

Cache extensions for django, including better Valkey/Redis backends and an admin interface.

Topics

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages