class Dict(modal.object.Provider)

A distributed dictionary available to Modal apps.

Keys and values can be essentially any object, so long as it can be serialized by cloudpickle, including Modal objects.

A Dict’s lifetime matches the lifetime of the app it’s attached to. On app completion or after stopping an app any associated Dict objects are cleaned up.


This is the constructor object, used only to attach a DictHandle to an app. To interact with Dict contents, use DictHandle objects that are attached to the live app once an app is running.

import modal

stub = modal.Stub()
stub.some_dict = modal.Dict()
# stub.some_dict["message"] = "hello world" # TypeError!

if __name__ == "__main__":
    with as app:
        handle = app.some_dict
        handle["message"] = "hello world"  # OK ✔️
def __init__(self, data={}):

Create a new dictionary, optionally filled with initial data.


class DictHandle(modal.object.Handle)

Handle for interacting with the contents of a Dict

stub.some_dict = modal.Dict()

if __name__ == "__main__":
    with as app:
        app.some_dict["message"] = "hello world"


def get(self, key: Any) -> Any:

Get the value associated with the key.

Raises KeyError if the key does not exist.


def contains(self, key: Any) -> bool:

Check if the key exists.


def len(self) -> int:

Returns the length of the dictionary.


def update(self, **kwargs) -> None:

Update the dictionary with additional items.


def put(self, key: Any, value: Any) -> None:

Add a specific key-value pair in the dictionary.


def pop(self, key: Any) -> Any:

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