Registry / web-framework / django-cache-url

django-cache-url

library3.4.6pypypi✓ verified 86d ago

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.

web-framework database

pip install django-cache-url

github ↗package ↗

INSTALL

IMPORT

SIG · DJANGO-CACHE-URL

django-cache-url

web-frameworkpythonv3.4.6

Install

1.5s avg

Import

10ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.4.6 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.915 runs

installs and imports cleanly · install 0.0s · import 0.011s · 17.8MB

glibc

py 3.10–3.915 runs

installs and imports cleanly · install 1.5s · import 0.007s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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()}")

Debug

Known issues

gotchaFor 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.

affects: Django >= 4.2

gotchaUsing 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).

affects: All versions

gotchaCache 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.

affects: All versions

Errors

Common errors & fixes

django.core.exceptions.ImproperlyConfigured: Unknown cache backend: 'redis'

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.

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.

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.

Upgrade

Version history

3.4.6latest on PyPI · released Jan 24, 2026

Audit

Dependencies

django-redisoptionalRequired for using Redis, Rediss, or Hiredis cache backends.

pymemcacheoptionalRequired for using the pymemcache cache backend.

django-pylibmcoptionalRequired for using the djangopylibmc cache backend (SASL-based memcached).

uwsgicacheoptionalRequired for using the uwsgicache backend.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/epicserve/django-cache-url ↗

packagehttps://pypi.org/project/django-cache-url/ ↗