class SharedVolume(modal.object.Provider)

A shared, writable file system accessible by one or more Modal functions.

By attaching this file system as a mount to one or more functions, they can share and persist data with each other.


import modal

stub = modal.Stub()

@stub.function(shared_volumes={"/root/foo": modal.SharedVolume()})
def f():

It is often the case that you would want to persist a shared volume object separately from the currently attached app. Refer to the persistence guide section to see how to persist this object across app runs.

def __init__(self) -> None:

Construct a new shared volume, which is empty by default.


class SharedVolumeHandle(modal.object.Handle)

A handle to a Modal SharedVolume

Should typically not be used directly in a Modal function, and instead referenced through the file system, see modal.SharedVolume.

Also see the CLI methods for accessing shared volumes:

modal volume --help

A SharedVolumeHandle can however be useful for some local scripting scenarios, e.g.:

vol = modal.lookup("my-shared-volume")
for chunk in vol.read_file("my_db_dump.csv"):


def write_file(self, remote_path: str, fp: BinaryIO):

Write from a file object to a path on the shared volume, atomically.

Will create any needed parent directories automatically

If remote_path ends with / it’s assumed to be a directory and the file will be uploaded with its current name to that directory.


def read_file(self, path: str) -> AsyncIterator[bytes]:

Read a file from the shared volume


def listdir(self, path: str) -> List[api_pb2.SharedVolumeListFilesEntry]:

List all files in a directory in the shared volume.

  • Passing a directory path lists all files in the directory (names are relative to the directory)
  • Passing a file path returns a list containing only that file’s listing description.
  • Passing a glob path (including at least one * or ** sequence) returns all files matching that glob path (using absolute paths)


def remove_file(self, path: str, recursive=False):

Remove a file in a shared volume