class uwsgiconf.options.caching.Caching(*args, **kwargs)


uWSGI includes a very fast, all-in-memory, zero-IPC, SMP-safe, constantly-optimizing, highly-tunable, key-value store simply called “the caching framework”.

A single uWSGI instance can create an unlimited number of “caches” each one with different setup and purpose.

set_basic_params(*, no_expire: bool = None, expire_scan_interval: int = None, report_freed: bool = None)
  • no_expire – Disable auto sweep of expired items. Since uWSGI 1.2, cache item expiration is managed by a thread in the master process, to reduce the risk of deadlock. This thread can be disabled (making item expiry a no-op) with the this option.
  • expire_scan_interval – Set the frequency (in seconds) of cache sweeper scans. Default: 3.
  • report_freed

    Constantly report the cache item freed by the sweeper.


    Use only for debug.

add_item(key: str, value: str, *, cache_name: str = None)

Add an item into the given cache.

This is a commodity option (mainly useful for testing) allowing you to store an item in a uWSGI cache during startup.

  • key
  • value
  • cache_name – If not set, default will be used.
add_file(filepath: Union[str, pathlib.Path], *, gzip: bool = False, cache_name: str = None)

Load a static file in the cache.


Items are stored with the filepath as is (relative or absolute) as the key.

  • filepath
  • gzip – Use gzip compression.
  • cache_name – If not set, default will be used.
add_cache(name: str, *, max_items: int, no_expire: bool = None, store: str = None, store_sync_interval: int = None, store_delete: bool = None, hash_algo: str = None, hash_size: int = None, key_size: int = None, udp_clients: Union[str, List[str]] = None, udp_servers: Union[str, List[str]] = None, block_size: int = None, block_count: int = None, sync_from: Union[str, List[str]] = None, mode_bitmap: bool = None, use_lastmod: bool = None, full_silent: bool = None, full_purge_lru: bool = None)

Creates cache. Default mode: single block.


This uses new generation cache2 option available since uWSGI 1.9.


When at least one cache is configured without full_purge_lru and the master is enabled a thread named “the cache sweeper” is started. Its main purpose is deleting expired keys from the cache. If you want auto-expiring you need to enable the master.

  • name – Set the name of the cache. Must be unique in an instance.
  • max_items

    Set the maximum number of cache items.


    Effective number of items is max_items - 1 - the first item of the cache is always internally used as “NULL/None/undef”.

  • no_expire – If True cache items won’t expire even if instructed to do so by cache set method.
  • store – Set the filename for the persistent storage. If it doesn’t exist, the system assumes an empty cache and the file will be created.
  • store_sync_interval – Set the number of seconds after which msync() is called to flush memory cache on disk when in persistent mode. By default it is disabled leaving the decision-making to the kernel.
  • store_delete – uWSGI, by default, will not start if a cache file exists and the store file does not match the configured items/blocksize. Setting this option will make uWSGI delete the existing file upon mismatch and create a new one.
  • hash_algo

    Set the hash algorithm used in the hash table. Current options are:

    • djb33x (default)
    • murmur2
  • hash_size

    This is the size of the hash table in bytes. Generally 65536 (the default) is a good value.


    Change it only if you know what you are doing or if you have a lot of collisions in your cache.

  • key_size – Set the maximum size of a key, in bytes. Default: 2048.
  • udp_clients – List of UDP servers which will receive UDP cache updates.
  • udp_servers – List of UDP addresses on which to bind the cache to wait for UDP updates.
  • block_size

    Set the size (in bytes) of a single block.


    It’s a good idea to use a multiple of 4096 (common memory page size).

  • block_count – Set the number of blocks in the cache. Useful only in bitmap mode, otherwise the number of blocks is equal to the maximum number of items.
  • sync_from – List of uWSGI addresses which the cache subsystem will connect to for getting a full dump of the cache. It can be used for initial cache synchronization. The first node sending a valid dump will stop the procedure.
  • mode_bitmap

    Enable (more versatile but relatively slower) bitmap mode.


    Considered production ready only from uWSGI 2.0.2.

  • use_lastmod – Enabling will update last_modified_at timestamp of each cache on every cache item modification. Enable it if you want to track this value or if other features depend on it. This value will then be accessible via the stats socket.
  • full_silent

    By default uWSGI will print warning message on every cache set operation if the cache is full. To disable this warning set this option.


    Available since 2.0.4.

  • full_purge_lru

    Allows the caching framework to evict Least Recently Used (LRU) item when you try to add new item to cache storage that is full.


    no_expire argument will be ignored.