Install & Compatibility
Where this runs
tested against v1.5.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
25MB installed
● package 25MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
make_region
✓ from dogpile.cache import make_region
The primary entry point for creating a cache region.
CacheRegion
✓ from dogpile.cache.region import CacheRegion
The class representing a configured cache region, often instantiated via make_region().
NO_VALUE
✓ from dogpile.cache.api import NO_VALUE
A sentinel value indicating a cache miss, distinct from `None`.
This quickstart demonstrates how to set up a cache region with the DBM file-based backend and use the `@region.cache_on_arguments()` decorator to cache the result of an expensive function. Subsequent calls with the same arguments will retrieve the cached value until it expires.
from dogpile.cache import make_region
import time
import os
# Configure a region using the DBM backend (file-based cache)
# Replace with 'dogpile.cache.redis' or 'dogpile.cache.pylibmc' for other backends
region = make_region(name='my_cache').configure(
backend='dogpile.cache.dbm',
expiration_time=3600, # seconds
arguments={'filename': 'cache.dbm'}
)
@region.cache_on_arguments()
def get_expensive_data(param1, param2):
"""Simulate an expensive computation."""
print(f"--- Computing data for {param1}, {param2} ---")
time.sleep(1) # Simulate work
return f"Data for {param1}-{param2} at {time.time()}"
print("First call (should compute):")
print(get_expensive_data("arg_a", 1))
print("Second call (should be cached):")
print(get_expensive_data("arg_a", 1))
print("Third call with different arguments (should compute):")
print(get_expensive_data("arg_b", 2))
# Clean up the cache file created for the DBM backend
if os.path.exists('cache.dbm'):
os.remove('cache.dbm')
Debug
Known issues
breakingPython 3.8 support was dropped in `dogpile.cache` version 1.4.0. The minimum required Python version is now 3.10. Users on older Python versions must remain on `dogpile.cache < 1.4.0`. [cite: rel_1_4_0, 5]fixUpgrade Python to 3.10 or newer, or pin `dogpile-cache < 1.4.0`.
affects: <=1.3.x
breakingWhen integrating with SQLAlchemy, caching mechanics changed in SQLAlchemy 1.4 (and 2.0+). The `CachingQuery` subclass approach from `dogpile.cache` examples for SQLAlchemy 1.3 is deprecated; new implementations should use the `do_orm_execute()` event model for caching with `Session.scalars(select(Thing))` interface.fixConsult `dogpile.cache` and SQLAlchemy documentation for updated SQLAlchemy caching recipes utilizing the `do_orm_execute()` event model and the unified `Session.scalars(select(...))` interface.
affects: >=1.4.0
gotchaNew parameters `lock_blocking_timeout`, `lock_blocking` were added to Redis and Valkey backends in 1.4.1, and `lock_prefix` in 1.5.0. These control the distributed locking behavior and prefixing of lock keys. [cite: rel_1_4_1, rel_1_5_0]fixReview the documentation for the `RedisBackend` or `ValkeyBackend` to understand and configure these new locking parameters as needed for your application's concurrency and key management requirements.
affects: All versions, especially when upgrading to >=1.4.1
gotchaThe `RedisClusterBackend` introduced in version 1.3.2 had runtime typing errors that were fixed in version 1.3.4. Users attempting to use Redis Cluster support should ensure they are on `dogpile.cache` 1.3.4 or a newer version to avoid these issues. [cite: rel_1_3_2, rel_1_3_4]fixUpgrade to `dogpile.cache` version 1.3.4 or later if using or planning to use `RedisClusterBackend`.
affects: 1.3.2, 1.3.3
gotchaWhile `dogpile.cache` is designed to prevent 'cache stampede' using a 'dogpile lock,' misconfiguration or over-reliance on locks in extremely high-traffic or complex scenarios can still introduce performance bottlenecks or potential deadlocks.fixCarefully design your caching strategy, consider `expiration_time` values, and monitor application performance, especially in scenarios with many concurrent requests. Optimize key generation and data creation functions to minimize lock contention.
affects: All versions
Errors
Common errors & fixes
ImportError: No module named fcntl
This error typically occurs when using the `dogpile.cache.dbm` backend on Windows, as the `fcntl` module, which it uses for file locking, is Unix-specific and not available on Windows systems.
fixUse a cache backend that is compatible with Windows, such as `dogpile.cache.memory` (in-process), `dogpile.cache.redis`, or `dogpile.cache.pylibmc` (Memcached), or implement a custom file lock using a Windows-compatible library.
AttributeError: 'CacheRegion' object has no attribute 'expiration_time'
This `AttributeError` (or similar ones related to backend properties) usually indicates that a `CacheRegion` object was created using `make_region()` but its `configure()` method has not been called before attempting to use it or its decorated functions, meaning the backend and its settings are not yet initialized.
fixEnsure that the `region.configure(backend_name, **kwargs)` method is called on the `CacheRegion` instance before any cache operations (like `get_or_create()` or using `@region.cache_on_arguments()`).
TypeError: '<' not supported between instances of 'dict' and 'int'
This specific `TypeError` (or `dogpile.cache.api.CantDeserializeException`) can arise during serialization/deserialization, especially with specific Python versions (like PyPy) or when the default `pickle` serializer encounters complex or non-picklable objects, or if cached data becomes incompatible after application updates.
fixEnsure that objects being cached are compatible with the default `pickle` serializer. For non-standard objects or specific environment issues, configure a custom `serializer` and `deserializer` when setting up the cache region, or catch `CantDeserializeException` to regenerate the value.
dogpile.cache.exception.RegionAlreadyConfigured
This exception is raised when the `configure()` method is called more than once on the same `CacheRegion` instance without explicitly allowing re-configuration.
fixConfigure each `CacheRegion` instance only once, typically at application startup. If you genuinely need to re-configure a region (e.g., in testing or dynamic environments), pass `replace=True` as an argument to the `configure()` method: `region.configure('some_backend', replace=True)`. dogpile.cache.api.NO_VALUE (unexpectedly returned)
This constant is returned when a requested key is not found in the cache, has expired, or if the `CacheRegion` is not correctly shared or configured across different modules or processes, leading to isolated cache instances instead of a single, shared cache.
fixEnsure that the `CacheRegion` instance is a singleton or is properly imported and shared consistently across all parts of your application that are intended to use the same cache. Verify the `expiration_time` and the persistence configuration of your chosen backend.
Upgrade
Version history
1.5.0latest on PyPI · released Oct 11, 2025
Audit
Dependencies
decoratorrequiredRequired for function decorators like @cache_on_arguments.
stevedorerequiredUsed for loading backend plugins.
redisoptionalRequired for the RedisBackend and RedisClusterBackend.
valkey-pyoptionalRequired for the ValkeyBackend.
pylibmcoptionalRequired for the PylibmcBackend (a Memcached client).
python-memcachedoptionalRequired for the MemcachedBackend (another Memcached client).
pymemcacheoptionalRequired for the PyMemcacheBackend (another Memcached client).