django-redis - Redis Cache That Actually Works

django-redis is the Redis cache backend that doesn't suck. Maintained by Jazzband (they also maintain a bunch of other Python stuff that actually works).

Why Not Use Django's Built-in Cache?

Because it sucks ass for anything real. Django's default cache is fine for toy projects, but try doing atomic counters or cache invalidation patterns and you'll want to quit programming and become a fucking barista. You can't even reliably increment a counter without race conditions.

I spent 3 hours trying to implement a simple view counter with Django's cache before giving up. With django-redis it's literally cache.incr('views') and it works atomically.

Why Not Raw Redis?

You could use raw Redis, but then you're writing all the Django integration yourself. Been there, done that, wanted to die for 3 weeks straight.

Plus django-redis handles all the connection pooling, serialization, and error recovery that you'll end up implementing anyway.

What Makes This Different?

• Actually works in production: I've been using this for 2 years without major issues
• Redis-specific features: INCR/DECR that don't break, proper TTL management, pattern-based deletions
• Compression that matters: Cut our Redis memory usage by 70% with lz4 compression
• Connection pooling that doesn't blow up: Unlike some other shitty packages that leak connections like a broken fire hydrant

Performance Reality

Switching from Django's default to this + Redis on our API:

• Response times: went from ~300ms to under 50ms for cached views
• Database load: cut by 70-80% on read-heavy endpoints
• Memory usage: about 30% higher than memcached, but compression helps
• Throughput: we went from handling ~100 req/s to 400+ req/s on the same hardware

The compression thing saves your ass if you're caching large objects. Use lz4 unless you're desperate for RAM, then use zstd.

Common Gotchas I Learned the Hard Way

Connection exhaustion: Set max_connections properly or you'll hit Redis connection limits and your app will shit the bed during traffic spikes. Ask me how I know. Default is usually too low for production.

Serialization hell: Don't cache Django model instances directly - they have references to database connections and other unpickleable shit. Cache the .values() data instead.

TTL weirdness: cache.set(key, value, 0) means cache forever, not delete immediately. Spent 2 hours debugging why my cache wasn't expiring.

Redis version issues: Older Redis versions (pre-5.0) have different behavior for some commands. Check your version if weird shit happens.

Multiple Client Types (And Why You Care)

django-redis has different clients for different scenarios:

• DefaultClient: Standard Redis, works with primary/replica setups. Use this unless you have a specific reason not to.
• ShardClient: Splits data across multiple Redis instances. Only use this if you're actually hitting Redis limits (you probably aren't).
• HerdClient: Prevents the thundering herd problem where 1000 requests all try to regenerate the same expired cache key. Saved our ass during a traffic spike.

Found out about HerdClient the hard way after our homepage cache expired during Black Friday traffic and something like 200+ requests all hit the database at once trying to rebuild the same fucking cache key. Site went down for 15 minutes while I frantically tried to figure out why our perfectly fine database suddenly couldn't handle basic queries. HerdClient prevents this exact clusterfuck.

Serialization Options (Performance vs Compatibility)

• Pickle (default): Fast, Python-only. Fine for most cases.
• JSON: Slower but works with other languages. Use this if you're sharing Redis with non-Python services.
• MessagePack: Smaller than JSON, faster than pickle. Good middle ground if you care about network traffic.

Tested these on our API (mostly JSON responses):

• Pickle: fastest, ~150ms for 10MB
• JSON: slower, ~280ms for the same data
• MessagePack: middle ground, ~190ms but smaller payload

Compression (The Memory Saver)

We went from 4GB Redis memory usage to 1.2GB just by enabling lz4 compression. The CPU overhead is minimal (~10ms per request) and totally worth it.

• lz4: Fast compression, good enough for most use cases
• zstd: Better compression ratio, slightly slower. Use this if you're RAM-constrained.
• zlib/gzip: Don't bother unless you need compatibility with other systems

Redis-Specific Operations (Why This Matters)

Unlike Django's generic cache, you get actual Redis commands:

## Atomic counters (no race conditions)
cache.incr('page_views')  # Returns the new value

## Pattern-based operations (lifesaver for debugging)
cache.keys('user:*')  # Find all user-related keys
cache.delete_pattern('session:*')  # Clear all sessions

## TTL control (not just set-and-forget)
cache.expire('key', 60)  # Extend expiration
cache.ttl('key')  # Check how long until expiration

These operations are thread-safe and atomic - crucial when you have multiple Django processes hammering Redis simultaneously.

High Availability (For When Redis Dies)

Sentinel support: If your primary Redis goes down, Sentinel automatically switches to a replica. django-redis handles this transparently - your app doesn't even know it happened.

Error handling: Set IGNORE_EXCEPTIONS = True and django-redis will gracefully degrade when Redis is down. Your app stays up, just without caching. Much better than the whole site going down because Redis hiccupped.

Production Reality Check

SSL/TLS: Works fine with Redis cloud providers. Had to tweak certificate validation for our corporate network, but the docs actually helped.

Connection pooling: Uses redis-py's connection pool, which is solid. We run 50 connections max and never hit the limit, even when everything's on fire.

Memory usage: Redis uses more memory than Memcached, but the compression features make up for it. Plus you get persistence and all the Redis data structures.

Version Reality

The latest stable is 6.0.0 (June 2025). Been using it for months without issues. The upgrade from 5.4.0 broke stuff for anyone still on Python 3.8 - they dropped support for it.

Main improvements in 6.x series:

• Django 5.2+ support (finally)
• Dropped Python 3.8 support (about time - it's EOL anyway)
• Better error handling for connection failures

Jazzband maintains this pretty well. Updates come out every few months, usually just bug fixes and Django compatibility.