diskcache-community

Disk and file backed persistent cache for Python, built on SQLite

[Tutorial] - [API] - [Benchmarks] - [Docs] - [Changelog]

Important

This is a community fork of python-diskcache, whose last release was 5.6.3 in August 2023. It is published on PyPI as diskcache-community and imported as diskcache_community, so it installs next to the upstream diskcache package. It carries the fix path for CVE-2025-69872 and reads and writes the same cache directories as 5.6.3. See Why this fork, Migrating from diskcache and Fix CVE-2025-69872 in diskcache.

Install

pip install diskcache-community

The package is imported as diskcache_community and never touches the upstream diskcache package, so both can be installed in the same environment; see Migrating from diskcache.

Usage

from diskcache_community import Cache

cache = Cache('cache')                 # the directory is created with mode 0700
cache.set('answer', 42, expire=3600, tag='math')
cache['config'] = {'debug': False}
cache.get('answer')                    # 42
cache.get('missing', default=None)
cache.evict('math')                    # delete every key tagged 'math'

Memoize function results across processes and restarts:

@cache.memoize(expire=600, ignore={'session'})
def fetch(url, session):
    return session.get(url).text

Shard across several SQLite files for higher write throughput, and plug the same cache into Django:

from diskcache_community import FanoutCache

cache = FanoutCache('cache', shards=8, timeout=1)

# settings.py
CACHES = {
    'default': {
        'BACKEND': 'diskcache_community.DjangoCache',
        'LOCATION': '/var/tmp/django_cache',
        'SHARDS': 8,
        'DISK': 'diskcache_community.SafeDisk',  # restricted unpickling, see below
    }
}

Caches shared with untrusted writers should use SafeDisk, which unpickles only a fixed set of built-in types and keeps file reads inside the cache directory:

from diskcache_community import Cache, SafeDisk

cache = Cache('cache', disk=SafeDisk)

Fix CVE-2025-69872 in diskcache covers caches that libraries create for you, your own classes, and entries already in the cache.

Features

• Cache, FanoutCache and DjangoCache for key-value caching with expiry, tags, size limits and LRU, LFU and other eviction policies
• Deque and Index: persistent, cross-process collections.deque and dict
• Recipes for memoization with stampede prevention, cross-process locks, semaphores and throttling
• Thread-safe and process-safe, with fork-safe connection handling
• Read-only mode, automatic when the directory is not writable
• Opt-in SafeDisk for caches whose directory other users can write to
• Pure Python on top of the standard library sqlite3; no server, no compiler
• Tested on CPython 3.10 to 3.14 on Linux, macOS and Windows
• Gets in about 2.6 µs and sets in about 19 µs on an Apple M5 Pro in the benchmarks against memcached, Redis, lmdb, sqlitedict and shelve; sets are 9 to 14 % faster than in diskcache 5.6.3, and twice as fast for 1 MB values

Why this fork

The upstream project stopped releasing after 5.6.3 (August 2023) and its last commit landed in March 2024. In 2025, CVE-2025-69872 was published against every released version: the cache reads pickled values with pickle.load, so anyone who can write into the cache directory can run code in the process that reads from it. The package still works, but scanners flag it and there is no fixed upstream version.

This fork publishes the same library as diskcache-community. It keeps the cache.db schema, the file layout, the serialization modes and the memoize key format unchanged, so a 5.6.3 process opens a directory written by this fork and the reverse. It adds the opt-in SafeDisk, creates cache directories with mode 0700, opens read-only directories read-only, closes the per-thread SQLite connections it used to leak, and survives fork. The package is imported as diskcache_community, so a project can move to it while other dependencies in the same environment still use the upstream diskcache. The changelog lists every change and SECURITY.md describes what is and is not fixed.

DiskCache was written and maintained by Grant Jenks from 2016 to 2023. This fork keeps his license, copyright and author credit; see NOTICE.

Migrating from diskcache

The public API and the files on disk are unchanged; only the import name differs. Install the fork and change the imports:

pip install diskcache-community

import diskcache_community as diskcache       # was: import diskcache
from diskcache_community import Cache          # was: from diskcache import Cache

In Django settings, use 'diskcache_community.DjangoCache' and 'diskcache_community.SafeDisk'. Existing cache directories open as they are, and a 5.6.3 process still opens directories written by the fork.

The migration guide lists the few behaviour changes since 5.6.3 and how to go back.

The upstream diskcache package can stay installed, for example when another dependency requires it. Each library uses the package it imports. A library that wants to support both can import whichever is present:

try:
    import diskcache_community as diskcache
except ImportError:
    import diskcache

Documentation

The documentation is at diskcache-community.readthedocs.io:

• Fix CVE-2025-69872 in diskcache
• Migrating from diskcache 5.6.3
• Tutorial
• API reference
• Benchmarks against memcached, Redis, lmdb, sqlitedict and shelve, the Django cache backends, and diskcache 5.6.3 (measured 2026-10-12)
• Old benchmarks from 2019, measured by upstream for version 4: Cache and DjangoCache
• Comparisons with other key-value stores and caching libraries
• Case studies: web crawler, landing page caching
• Development

Comparison

	diskcache	dbm	shelve	sqlitedict	pickleDB
Atomic	Always	Maybe	Maybe	Maybe	No
Thread-safe	Yes	No	No	Yes	No
Process-safe	Yes	No	No	Maybe	No
Eviction	LRU, LFU, more	None	None	None	None
Serialization	Customizable	None	Pickle	Customizable	JSON
Data types	Mapping, deque	Mapping	Mapping	Mapping	Mapping

The full comparisons page covers features, quality and timings in detail.

Contributing and security

Bug reports and pull requests are welcome on GitHub. CONTRIBUTING.md explains the compatibility contract and how to run the tests. Report vulnerabilities privately as described in SECURITY.md.

License

Copyright 2016-2023 Grant Jenks. Modifications in this fork are copyright 2026 diskcache-community contributors. Licensed under the Apache License, Version 2.0.