Install & Compatibility
Where this runs
tested against v0.14.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.
SimpleCache
✓ from cachelib import SimpleCache
FileSystemCache
✓ from cachelib import FileSystemCache
RedisCache
✓ from cachelib import RedisCache
This quickstart demonstrates how to initialize a `SimpleCache` (in-memory) and a `FileSystemCache` (file-based) to store, retrieve, check for existence, and delete cached values. It highlights basic `set`, `get`, `has`, and `delete` operations. For `FileSystemCache`, a temporary directory is used for demonstration purposes.
from cachelib import SimpleCache
# Initialize an in-memory cache
cache = SimpleCache(threshold=500, default_timeout=300)
# Set a value
cache.set("my_key", "my_value", timeout=60)
# Get a value
value = cache.get("my_key")
print(f"Retrieved: {value}")
# Check if a key exists
exists = cache.has("my_key")
print(f"Key 'my_key' exists: {exists}")
# Delete a key
cache.delete("my_key")
exists_after_delete = cache.has("my_key")
print(f"Key 'my_key' exists after delete: {exists_after_delete}")
# Example with FileSystemCache (requires a directory)
import os
import tempfile
with tempfile.TemporaryDirectory() as temp_dir:
file_cache = FileSystemCache(cache_dir=os.path.join(temp_dir, "cache"), threshold=100)
file_cache.set("file_key", "file_value", timeout=300)
file_value = file_cache.get("file_key")
print(f"Retrieved from file cache: {file_value}")
file_cache.clear() # Clean up temporary cache dir
Debug
Known issues
breakingPython 3.7 support was dropped in Cachelib 0.11.0. Older versions (0.7.0) dropped Python 3.6 support. Ensure your Python environment is 3.8+.fixUpgrade to Python 3.8 or newer, or pin cachelib to a compatible older version if Python 3.7 or 3.6 is strictly required.
affects: >=0.11.0 (for Python 3.7), >=0.7.0 (for Python 3.6)
deprecatedThe methods `RedisCache.load_object` and `RedisCache.dump_object` were removed in Cachelib 0.8.0. These were internal methods and their direct use would have caused breaking changes.fixAvoid direct reliance on internal serialization methods. The library handles serialization internally using `RedisSerializer`.
affects: >=0.8.0
gotchaThe `FileSystemCache` requires exclusive use of its `cache_dir` parameter. If other processes or manual interventions modify files within this directory, the cache may behave unexpectedly (e.g., deleting unintended files).fixDedicate a unique directory for each `FileSystemCache` instance and ensure no other process or manual operation interacts with its contents.
affects: All versions
gotchaIn Cachelib 0.13.0, the `hashlib.md5` default for `FileSystemCache` was changed to be lazy-loaded. This was to prevent issues in FIPS-compliant environments where MD5 might not be available at import time. If you relied on `hashlib.md5` being available immediately at import, or if you need to specify a different hash method for FIPS compliance, consider this change.fixIf `hashlib.md5` is unavailable or restricted in your environment, configure `FileSystemCache` with a custom `hash_method` during initialization. The library will lazy-load `hashlib.md5` if no alternative is provided.
affects: >=0.13.0
gotchaIn `RedisCache` version 0.12.0, a fix was implemented to correctly handle a string for the `host` parameter, where previously passing a non-string 'host object' might have caused issues.fixAlways pass a string (e.g., 'localhost') or a `redis.Redis` client instance to the `host` parameter of `RedisCache`.
affects: >=0.12.0 (fix applied)
breakingSpecific cache classes (e.g., `FileSystemCache`, `RedisCache`, `SimpleCache`) must be explicitly imported from the `cachelib` module before use. Attempting to use them without an explicit import will result in a `NameError`.fixEnsure that all `cachelib` classes are properly imported (e.g., `from cachelib import FileSystemCache`) before they are used in your code.
affects: All versions
breakingCachelib 0.13.0 removed all package extras (e.g., `[redis]`, `[memcached]`, `[dynamodb]`, `[mongodb]`). Drivers for external backends are now provided as separate packages (e.g., `cachelib-redis`, `cachelib-memcached`). Users must install these backend-specific packages explicitly.fixInstall backend drivers using their dedicated package names (e.g., `pip install cachelib-redis`, `pip install cachelib-memcached`) instead of using extras on the main `cachelib` package.
affects: >=0.13.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cachelib'
The 'cachelib' library is not installed in your Python environment or the environment where your application is running.
fixInstall the cachelib library using pip: `pip install cachelib`
ModuleNotFoundError: No module named 'werkzeug.contrib.cache'
The `werkzeug.contrib.cache` module was deprecated in Werkzeug 1.0 and extracted into the separate `cachelib` library.
fixReplace `from werkzeug.contrib.cache import ...` with `from cachelib import ...` (or a specific cache backend like `from cachelib.redis import RedisCache`) and ensure `cachelib` is installed.
AttributeError: 'module' object has no attribute 'replace'
This error occurs when using cachelib with Python 2.x because cachelib utilizes `os.replace()`, which was introduced in Python 3.3 and is not available in Python 2.
fixUpgrade your Python environment to Python 3.3 or newer. If Python 2.x compatibility is strictly required, you might need to pin an older version of cachelib that doesn't use `os.replace` or implement a fallback, though upgrading Python is strongly recommended.
Can not lock shm metadata file: Device or resource busy
This error typically occurs when using cachelib's persistent cache with multiple processes attempting to operate on the same cache path simultaneously, as cachelib locks the path to ensure single-instance operation.
fixEnsure that only one process is accessing a given persistent cache path at a time. This may involve identifying and terminating zombie processes, or configuring separate cache paths for different application instances.
Upgrade
Version history
0.17.0latest on PyPI · released Aug 24, 2026
Audit
Dependencies
redisoptionalRequired for RedisCache backend.
python-memcachedoptionalRequired for MemcachedCache backend. Alternative: pylibmc.
boto3optionalRequired for DynamoDbCache backend.
pymongooptionalRequired for MongoDbCache backend.