modal.Dict

Distributed dictionary for storage in Modal apps.

Dict contents can be essentially any object so long as they can be serialized by cloudpickle. This includes other Modal objects. If writing and reading in different environments (eg., writing locally and reading remotely), it’s necessary to have the library defining the data type installed, with compatible versions, on both sides. Additionally, cloudpickle serialization is not guaranteed to be deterministic, so it is generally recommended to use primitive types for keys.

Lifetime of a Dict and its items

An individual Dict entry will expire after 7 days of inactivity (no reads or writes). The Dict entries are written to durable storage.

Legacy Dicts (created before 2025-05-20) will still have entries expire 30 days after being last added. Additionally, contents are stored in memory on the Modal server and could be lost due to unexpected server restarts. Eventually, these Dicts will be fully sunset.

Usage

The Dict class offers a few methods for operations that are usually accomplished in Python with operators, such as Dict.put and Dict.contains. The advantage of these methods is that they can be safely called in an asynchronous context by using the .aio suffix on the method, whereas their operator-based analogues will always run synchronously and block the event loop.

For more examples, see the guide.

hydrate 

Synchronize the local object with its identity on the Modal server.

It is rarely necessary to call this method explicitly, as most operations will lazily hydrate when needed. The main use case is when you need to access object metadata, such as its ID.

Added in v0.72.39: This method replaces the deprecated .resolve() method.

objects 

Namespace with methods for managing named Dict objects.

create 

Create a new Dict object.

Examples:

Dicts will be created in the active environment, or another one can be specified:

By default, an error will be raised if the Dict already exists, but passing allow_existing=True will make the creation attempt a no-op in this case.

Note that this method does not return a local instance of the Dict. You can use modal.Dict.from_name to perform a lookup after creation.

Added in v1.1.2.

list 

Return a list of hydrated Dict objects.

Examples:

Dicts will be retreived from the active environment, or another one can be specified:

By default, all named Dict are returned, newest to oldest. It’s also possible to limit the number of results and to filter by creation date:

Added in v1.1.2.

delete 

Delete a named Dict.

Warning: This deletes an entire Dict, not just a specific key. Deletion is irreversible and will affect any Apps currently using the Dict.

Examples:

Dicts will be deleted from the active environment, or another one can be specified:

Added in v1.1.2.

name 

ephemeral 

Creates a new ephemeral Dict within a context manager:

Usage:

from_name 

Reference a named Dict, creating if necessary.

This is a lazy method that defers hydrating the local object with metadata from Modal servers until the first time it is actually used.

from_id 

Construct a Dict from an id and look up the Dict metadata.

This is a lazy method that defers hydrating the local object with metadata from Modal servers until the first time it is actually used.

The ID of a Dict object can be accessed using .object_id.

Example:

info 

Return information about the Dict object.

clear 

Remove all items from the Dict.

get 

Get the value associated with a key.

Returns default if key does not exist.

contains 

Return if a key is present.

len 

Return the length of the Dict.

Note: This is an expensive operation and will return at most 100,000.

update 

Update the Dict with additional items.

put 

Add a specific key-value pair to the Dict.

Returns True if the key-value pair was added and False if it wasn’t because the key already existed and skip_if_exists was set.

pop 

Remove a key from the Dict, returning the value if it exists.

If key is not found, return default if provided, otherwise raise KeyError.

keys 

Return an iterator over the keys in this Dict.

Note that (unlike with Python dicts) the return value is a simple iterator, and results are unordered.

values 

Return an iterator over the values in this Dict.

Note that (unlike with Python dicts) the return value is a simple iterator, and results are unordered.

items 

Return an iterator over the (key, value) tuples in this Dict.

Note that (unlike with Python dicts) the return value is a simple iterator, and results are unordered.