modal.Volume

A writeable volume that can be used to share files between one or more Modal functions.

The contents of a volume is exposed as a filesystem. You can use it to share data between different functions, or to persist durable state across several instances of the same function.

Unlike a networked filesystem, you need to explicitly reload the volume to see changes made since it was mounted. Similarly, you need to explicitly commit any changes you make to the volume for the changes to become visible outside the current container.

Concurrent modification is supported, but concurrent modifications of the same files should be avoided! Last write wins in case of concurrent modification of the same file - any data the last writer didn’t have when committing changes will be lost!

As a result, volumes are typically not a good fit for use cases where you need to make concurrent modifications to the same file (nor is distributed file locking supported).

Volumes can only be reloaded if there are no open files for the volume - attempting to reload with open files will result in an error.

Usage

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 Volume objects.

create 

Create a new Volume object.

Examples:

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

By default, an error will be raised if the Volume 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 Volume. You can use modal.Volume.from_name to perform a lookup after creation.

Added in v1.1.2.

list 

Return a list of hydrated Volume objects.

Examples:

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

By default, all named Volumes 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 Volume.

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

Examples:

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

Added in v1.1.2.

name 

read_only 

Configure Volume to mount as read-only.

Example

The Volume is mounted as a read-only volume in a function. Any file system write operation into the mounted volume will result in an error.

Added in v1.0.5.

from_name 

Reference a Volume by name, creating if necessary.

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

from_id 

Construct a Volume from an id and look up the Volume 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 Volume object can be accessed using .object_id.

Example:

ephemeral 

Creates a new ephemeral volume within a context manager:

Usage:

info 

Return information about the Volume object.

commit 

Commit changes to a mounted volume.

If successful, the changes made are now persisted in durable storage and available to other containers accessing the volume.

reload 

Make latest committed state of volume available in the running container.

Any uncommitted changes to the volume, such as new or modified files, may implicitly be committed when reloading.

Reloading will fail if there are open files for the volume.

iterdir 

Iterate over all files in a directory in the volume.

Passing a directory path lists all files in the directory. For a file path, return only that file’s description. If recursive is set to True, list all files and folders under the path recursively.

listdir 

List all files under a path prefix in the modal.Volume.

Passing a directory path lists all files in the directory. For a file path, return only that file’s description. If recursive is set to True, list all files and folders under the path recursively.

read_file 

Read a file from the modal.Volume.

Note - this function is primarily intended to be used outside of a Modal App. For more information on downloading files from a Modal Volume, see the guide.

Example:

remove_file 

Remove a file or directory from a volume.

copy_files 

Copy files within the volume from src_paths to dst_path. The semantics of the copy operation follow those of the UNIX cp command.

The src_paths parameter is a list. If you want to copy a single file, you should pass a list with a single element.

src_paths and dst_path should refer to the desired location inside the volume. You do not need to prepend the volume mount path.

Usage

Note that if the volume is already mounted on the Modal function, you should use normal filesystem operations like os.rename() and then commit() the volume. The copy_files() method is useful when you don’t have the volume mounted as a filesystem, e.g. when running a script on your local computer.

batch_upload 

Initiate a batched upload to a volume.

To allow overwriting existing files, set force to True (you cannot overwrite existing directories with uploaded files regardless).

Example:

rename