{"id":630,"library":"diskcache","title":"DiskCache","description":"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.","status":"active","version":"5.6.3.post1","language":"en","source_language":"en","source_url":"https://github.com/grantjenks/python-diskcache","tags":["cache","disk","persistence","thread-safe","process-safe"],"install":[{"cmd":"pip install diskcache","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"Cache","correct":"from diskcache import Cache"},{"symbol":"json_serializer","correct":"from diskcache import json_serializer"}],"quickstart":{"code":"from diskcache import Cache\nimport os\n\n# Create a cache in a specified directory\n# It's good practice to manage cache directories, e.g., in a temp folder or user data dir.\ncache_dir = os.path.join(os.getcwd(), 'my_app_cache')\n\n# Use a context manager to ensure the cache is properly closed\nwith Cache(cache_dir, size_limit=1e9) as cache:\n    # Set a key-value pair\n    cache.set('greeting', 'Hello, DiskCache!')\n\n    # Get a value by key\n    value = cache.get('greeting')\n    print(f\"Retrieved value: {value}\")\n\n    # Check if a key exists\n    if 'another_key' not in cache:\n        cache.set('another_key', 123)\n    print(f\"Another key's value: {cache.get('another_key')}\")\n\n# The cache persists after the 'with' block, and can be reopened.\nwith Cache(cache_dir) as cache:\n    print(f\"Reopened cache value: {cache.get('greeting')}\")\n\n# Clean up the cache directory for repeated runs in examples\n# In a real application, you would manage its lifecycle.\nimport shutil\nif os.path.exists(cache_dir):\n    shutil.rmtree(cache_dir)\n","lang":"python","description":"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."},"warnings":[{"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.","message":"DiskCache 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.","severity":"breaking","affected_versions":">=5.0.0 (when upgrading from <5.0.0)"},{"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.","message":"When 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`.","severity":"gotcha","affected_versions":"All versions when using `json_serializer`"},{"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.","message":"Not 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"DiskCache 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T16:59:51.133Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"Attempting to store an object that cannot be converted to JSON when `json_serializer` is used for the cache.","error":"TypeError: Object of type <YourCustomClass> is not JSON serializable"},{"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.","cause":"The Python process does not have write permissions to the specified cache directory or its parent directories.","error":"PermissionError: [Errno 13] Permission denied: '/path/to/cache/file'"},{"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.","cause":"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).","error":"FileNotFoundError: [Errno 2] No such file or directory: '/path/to/cache/file'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"5.6.3","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":3.1,"disk_size":"18.1M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":3.1,"disk_size":"18.1M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.7,"import_time_s":0.04,"mem_mb":3.1,"disk_size":"19M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":3.1,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":3.1,"disk_size":"20.0M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":3.1,"disk_size":"20.0M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.7,"import_time_s":0.06,"mem_mb":3.1,"disk_size":"21M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":3.1,"disk_size":"21M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":3.2,"disk_size":"11.9M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":3.2,"disk_size":"11.9M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0.06,"mem_mb":3.2,"disk_size":"12M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":3.2,"disk_size":"12M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":3.4,"disk_size":"11.6M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":3.4,"disk_size":"11.5M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0.05,"mem_mb":3.2,"disk_size":"12M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":3.2,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":3,"disk_size":"17.6M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":3,"disk_size":"17.6M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2,"import_time_s":0.04,"mem_mb":3,"disk_size":"18M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":3,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}