Registry / web-framework / django-cachalot

django-cachalot

library2.9.0pypypi✓ verified 88d ago

django-cachalot is a Django package that automatically caches all Django ORM queries and transparently invalidates them when data changes. It aims to provide significant performance improvements by reducing database hits without requiring developers to write explicit caching logic. The library is actively maintained, with version 2.9.0 supporting recent Django releases and Python versions, and new releases frequently adapting to Django's evolution.

web-framework database http-networking

pip install django-cachalot

github ↗package ↗

INSTALL

IMPORT

SIG · DJANGO-CACHALOT

django-cachalot

web-frameworkpythonv2.9.0

Install

3.5s avg

Import

—

Disk

66MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.9.0 · 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.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 66.9MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 3.5s · import 0.000s · 67MB

66MB installed

● package 66MB

Code

Verified usage

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

default_app_config

✓ from cachalot import default_app_config

✗ import cachalot

To enable django-cachalot, add 'cachalot' to your `INSTALLED_APPS` and ensure you have a Django cache backend configured in your `CACHES` setting. For production, a shared cache like Redis or Memcached is recommended. For local development, `LocMemCache` can be used, but be aware of its limitations in multi-process environments. It's often beneficial to configure `IGNORE_EXCEPTIONS` for your cache backend to prevent application crashes if the cache service is unavailable.

import os # settings.py SECRET_KEY = os.environ.get('DJANGO_SECRET_KEY', 'a-very-secret-key') INSTALLED_APPS = [ # ... other apps 'django.contrib.admin', 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.messages', 'django.contrib.staticfiles', 'cachalot', ] # Configure a cache backend (e.g., Redis) CACHES = { 'default': { 'BACKEND': 'django_redis.cache.RedisCache', 'LOCATION': os.environ.get('REDIS_URL', 'redis://127.0.0.1:6379/1'), 'OPTIONS': { 'CLIENT_CLASS': 'django_redis.client.DefaultClient', 'IGNORE_EXCEPTIONS': True # Recommended for graceful degradation if cache is down } } } DATABASES = { 'default': { 'ENGINE': 'django.db.backends.postgresql', 'NAME': 'mydatabase', 'USER': 'mydatabaseuser', 'PASSWORD': 'password', 'HOST': '127.0.0.1', 'PORT': '5432', } } # To verify caching, you can add CachalotPanel to Django Debug Toolbar DEBUG_TOOLBAR_PANELS = [ # ... other panels 'cachalot.panels.CachalotPanel', ]

Debug

Known issues

breakingAs of v2.9.0, Django 3.2 support has been dropped. Ensure your Django project is running a supported version (Django 4.2, 5.2, or 6.0).

fix

Upgrade your Django project to a compatible version or use an older django-cachalot release that supports your Django version.

affects: >=2.9.0

breakingWith v2.6.0, support for Django 2.2 and 4.0 was dropped. Projects using these versions must stick to django-cachalot <2.6.0.

fix

Upgrade your Django project to a compatible version or use an older django-cachalot release.

affects: >=2.6.0, <2.9.0

gotchadjango-cachalot caches results on a per-table basis, not per-object. If a single object in a table is modified, all cached queries related to that entire table are invalidated. This can lead to frequent cache invalidations and potential performance degradation if tables experience a high rate of modifications (e.g., >50 modifications per minute).

fix

Evaluate if django-cachalot's per-table invalidation strategy aligns with your application's write patterns. For very high-write tables, consider alternative caching strategies (e.g., per-object caching with other libraries like `django-cacheops` or `django-cache-machine` for hot data, or manual caching for specific querysets) or optimize database queries directly.

affects: All

gotchaRaw SQL queries (e.g., `QuerySet.extra`, `Model.objects.raw`, `cursor.execute`) are not cached by django-cachalot because it cannot reliably detect all affected tables for proper invalidation. Any data retrieved via raw SQL will bypass the cache.

fix

If caching is critical for raw SQL queries, implement manual caching for those specific cases using Django's low-level cache API. Ensure that manual invalidation is handled correctly when underlying data changes.

affects: All

gotchaUsing `django.core.cache.backends.locmem.LocMemCache` (local memory cache) is not suitable for multi-process environments (e.g., Gunicorn with multiple workers, Celery, RQ) because the cache is not shared between processes, leading to stale data.

fix

For multi-process deployments, use a shared cache backend like Redis (`django-redis`) or Memcached.

affects: All

gotchaChanging the `CACHALOT_CACHE` setting to use a different cache alias in your `settings.py` will not automatically invalidate existing data in the *old* cache. This can lead to stale data being served until manually cleared.

fix

After modifying `CACHALOT_CACHE`, run `./manage.py invalidate_cachalot` to clear the cache, or manually clear the old cache alias using its specific API if you need to retain other cache data.

affects: All

gotchaA recursion issue in atomic transactions (`transaction.atomic`) was fixed in v2.9.0. Prior versions might encounter unexpected behavior or errors when cachalot interacts with complex atomic blocks.

fix

Upgrade to django-cachalot v2.9.0 or later to benefit from the fix for atomic transaction recursion issues.

affects: <2.9.0

Upgrade

Version history

2.9.0latest on PyPI · released Jan 28, 2026

Audit

Dependencies

DjangorequiredCore dependency for a Django application. Currently supports Django 4.2, 5.2, and 6.0.

django-redisoptionalCommon and recommended cache backend for production use.

python-memcachedoptionalAlternative Memcached cache backend.

pylibmcoptionalFaster Memcached cache backend, typically used with Django >= 1.7.

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/noripyt/django-cachalot ↗

packagehttps://pypi.org/project/django-cachalot/ ↗