Django Cache URL

3.4.6 · active · verified Thu Apr 16

This simple Django utility allows you to utilize the 12factor inspired CACHE_URL environment variable to configure your Django application. It supports various cache backends like locmem, db, file, memcached, and redis. The library is actively maintained, with a recent release on January 24, 2026.

Common errors

```
django.core.exceptions.ImproperlyConfigured: Unknown cache backend: 'redis'
```
cause The Python library for the 'redis' cache backend (django-redis) is not installed.

fix Install the required package: `pip install django-redis` (or `pymemcache`, `django-pylibmc`, `uwsgicache` for other backends specified in your CACHE_URL).
```
django.core.exceptions.ImproperlyConfigured: CACHE_URL environment variable is not set.
```
cause The `config()` function was called without the `CACHE_URL` environment variable being defined, and no default value was provided.

fix Set the `CACHE_URL` environment variable (e.g., `export CACHE_URL="locmem://"`) or provide a default directly in `settings.py`: `CACHES = {'default': config(default='locmem://')}`.
```
Cached pages are not updating correctly or show stale data for different users/requests.
```
cause The cache key generated by Django is not sufficiently distinguishing between different variations of a page (e.g., per user, or based on query parameters), or the cache is not being invalidated when underlying data changes.

fix Review Django's caching documentation, especially regarding `vary_on_headers`, `vary_on_cookie`, and `key_prefix`. Ensure that dynamic content that relies on user state or query parameters is properly accounted for in cache key generation, or implement manual cache invalidation where appropriate.

Warnings

gotcha For new projects using only Redis cache with Django 4.2 or newer, consider using Django's native `django.core.cache.backends.redis.RedisCache` backend directly, as it offers built-in Redis support. `django-cache-url` remains highly useful for other cache types, unified multi-backend configuration, or legacy projects.
Fix: For Redis-only, refer to Django's official documentation on Redis cache configuration. Otherwise, continue using `django-cache-url` for its intended purpose.
gotcha Using certain cache backends (e.g., Redis, Memcached, PyLibMC, UWSGI) via `django-cache-url` requires installing additional Python packages (e.g., `django-redis`, `pymemcache`). The library itself only provides the URL parsing logic, not the backend implementation.
Fix: Ensure you install the corresponding Python package for the cache backend specified in your `CACHE_URL` (e.g., `pip install django-redis` for `redis://` URLs).
gotcha Cache invalidation can be complex, especially with URL-based caching. If underlying data changes, a cached URL might serve stale content until its expiry. `django-cache-url` configures the cache, but managing invalidation remains an application-level concern.
Fix: Implement explicit cache invalidation strategies (e.g., `cache.delete()`, `cache.clear()`) or leverage Django's `vary_on_headers` / `vary_on_cookie` decorators for views where content depends on request headers or user context.

Install

pip install django-cache-url Install stable version

Imports

config
```
from django_cache_url import config
```
The primary function to parse a CACHE_URL environment variable.
parse
```
from django_cache_url import parse
```
Used to parse an arbitrary cache URL string, rather than an environment variable.

Quickstart

Configure your Django application's cache settings using the CACHE_URL environment variable, leveraging the `config` function. This example shows how to set up the default cache and a basic usage pattern.

import os
from django_cache_url import config

# Recommended: Set CACHE_URL in your environment, e.g., in .env file or deployment config
# Example: export CACHE_URL="redis://localhost:6379/1"
# Example: export CACHE_URL="memcached://127.0.0.1:11211"
# Example: export CACHE_URL="locmem://"

# In your Django settings.py:
CACHES = {
    'default': config(
        # Provide a default if CACHE_URL environment variable is not set
        default=os.environ.get('CACHE_URL', 'locmem://')
    )
}

# To parse an arbitrary URL string directly (not from env var):
# CACHES['custom_cache'] = parse('file:///tmp/django_cache')

# Example using the cache (e.g., in a view or management command)
from django.core.cache import cache

def my_cached_function():
    data = cache.get('my_key')
    if data is None:
        data = "Expensive calculation result!"
        cache.set('my_key', data, 60*5) # Cache for 5 minutes
    return data

print(f"Cache configured for backend: {CACHES['default']['BACKEND']}")
print(f"Retrieved data: {my_cached_function()}")

view raw JSON →