diskcache

library5.6.3pypiunverified

DiskCache is a pure-Python, thread-safe, and process-safe disk-backed persistent cache. It supports various data types, cache eviction policies, and can be used in web servers, for caching slow function results, and in batch jobs. The library is actively maintained with regular updates.

database serialization

pip install diskcache

homepage ↗

INSTALL

IMPORT

SIG · DISKCACHE

diskcache

databaseenv5.6.3

Install

1.7s avg

Import

57ms

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 v5.6.3 · 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.925 runs

installs and imports cleanly · install 0.0s · import 0.062s · 18.1MB

glibc

py 3.10–3.925 runs

installs and imports cleanly · install 1.7s · import 0.051s · 19MB

16MB installed

● package 16MB

Code

Verified usage

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

Cache

✓ from diskcache import Cache

json_serializer

✓ from diskcache import json_serializer

This quickstart demonstrates how to initialize a DiskCache instance, store and retrieve data, and clean up the cache directory. It uses a context manager (`with Cache(...)`) for proper cache management and shows basic `set` and `get` operations. A `size_limit` is included as a best practice.

from diskcache import Cache import os # Create a cache in a specified directory # It's good practice to manage cache directories, e.g., in a temp folder or user data dir. cache_dir = os.path.join(os.getcwd(), 'my_app_cache') # Use a context manager to ensure the cache is properly closed with Cache(cache_dir, size_limit=1e9) as cache: # Set a key-value pair cache.set('greeting', 'Hello, DiskCache!') # Get a value by key value = cache.get('greeting') print(f"Retrieved value: {value}") # Check if a key exists if 'another_key' not in cache: cache.set('another_key', 123) print(f"Another key's value: {cache.get('another_key')}") # The cache persists after the 'with' block, and can be reopened. with Cache(cache_dir) as cache: print(f"Reopened cache value: {cache.get('greeting')}") # Clean up the cache directory for repeated runs in examples # In a real application, you would manage its lifecycle. import shutil if os.path.exists(cache_dir): shutil.rmtree(cache_dir)

diskcache --version

Debug

Known issues

breakingDiskCache v5.0.0 introduced a breaking change in the internal cache format (pickle_version). Upgrading from pre-5.0 versions may render existing caches unreadable.

fix

Clear your existing cache directory before upgrading to DiskCache v5.0.0 or later. For example, delete the directory specified in `Cache('/path/to/cache')`. If data migration is critical, use a prior version to export data and then re-import it after upgrading.

affects: >=5.0.0 (when upgrading from <5.0.0)

gotchaWhen using `json_serializer` (e.g., `Cache(serializer=json_serializer)`), all objects stored must be JSON serializable. Custom objects, datetime objects, or non-serializable types will raise a `TypeError`.

fix

Ensure all objects are JSON-serializable. For custom objects, implement `__json__` or provide a custom serializer function. For types like `datetime`, convert them to strings (ISO format) before storing and parse them back upon retrieval.

affects: All versions when using `json_serializer`

gotchaNot setting a `size_limit` or `cull_limit` can lead to the cache growing indefinitely, consuming large amounts of disk space, especially in long-running applications or with large data items.

fix

Always initialize `Cache` with `size_limit` (maximum cache size in bytes) and/or `cull_limit` (maximum items before culling). Regularly call `cache.cull()` if automatic culling isn't sufficient for your eviction policy.

affects: All versions

gotchaDiskCache relies on file locking for thread and process safety. This mechanism can be unreliable or lead to performance issues when the cache directory is located on Network File Systems (NFS), especially across different operating systems.

fix

Avoid placing DiskCache directories on NFS mounts if possible. If unavoidable, thoroughly test your application's concurrency under load and consider using a database-backed cache or a different caching solution for critical NFS-dependent workloads.

affects: All versions

Errors

Common errors & fixes

TypeError: Object of type <YourCustomClass> is not JSON serializable

Attempting to store an object that cannot be converted to JSON when `json_serializer` is used for the cache.

fix

Switch to the default `pickle` serializer (remove `serializer=json_serializer` from `Cache` initialization), or convert your objects to a JSON-serializable format (e.g., dictionary, list, string) before storing them. For custom classes, you might need to implement a custom serializer/deserializer pair.

PermissionError: [Errno 13] Permission denied: '/path/to/cache/file'

The Python process does not have write permissions to the specified cache directory or its parent directories.

fix

Ensure the user running the Python script has full read/write/execute permissions for the cache directory and its contents. This often occurs in containerized environments or on shared file systems. Change the cache directory to a user-writable location or adjust file system permissions.

FileNotFoundError: [Errno 2] No such file or directory: '/path/to/cache/file'

The cache directory specified to `Cache()` was deleted or does not exist, and the current operation requires an existing file within it (e.g., when the cache is being created or accessed by another process that deletes it).

fix

Ensure the base directory for the cache exists and is writable before initializing `Cache`. DiskCache will create the actual cache subdirectories, but its base path must be valid. Verify no external process is inadvertently deleting the cache directory while your application is running.

Upgrade

Version history

5.6.3latest on PyPI · released Aug 31, 2023

Audit

Dependencies

No dependency data recorded yet.

Agent activity

22 hits · last 30 days

node

Amazon

Resources

homepagehttp://www.grantjenks.com/docs/diskcache/ ↗