modal.NetworkFileSystem

class NetworkFileSystem(modal.object.Object)

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.

Usage

import modal

volume = modal.NetworkFileSystem.new()
stub = modal.Stub()

@stub.function(network_file_systems={"/root/foo": volume})
def f():
    pass

@stub.function(network_file_systems={"/root/goo": volume})
def g():
    pass

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

Also see the CLI methods for accessing network file systems:

modal nfs --help

A NetworkFileSystem can also be useful for some local scripting scenarios, e.g.:

vol = modal.NetworkFileSystem.lookup("my-network-file-system")
for chunk in vol.read_file("my_db_dump.csv"):
    ...
def __init__(self, *args, **kwargs):

new

@typechecked
@staticmethod
def new(cloud: Optional[str] = None) -> "_NetworkFileSystem":

Construct a new network file system, which is empty by default.

from_name

@staticmethod
def from_name(
    label: str,
    namespace=api_pb2.DEPLOYMENT_NAMESPACE_WORKSPACE,
    environment_name: Optional[str] = None,
    create_if_missing: bool = False,
) -> "_NetworkFileSystem":

Create a reference to a persisted network filesystem

persisted

@staticmethod
def persisted(
    label: str,
    namespace=api_pb2.DEPLOYMENT_NAMESPACE_WORKSPACE,
    environment_name: Optional[str] = None,
    cloud: Optional[str] = None,
) -> "_NetworkFileSystem":

Deploy a Modal app containing this object.

The deployed object can then be imported from other apps, or by calling NetworkFileSystem.from_name(label) from that same app.

Examples

# In one app:
volume = NetworkFileSystem.persisted("my-volume")

# Later, in another app or Python file:
volume = NetworkFileSystem.from_name("my-volume")

@stub.function(network_file_systems={"/vol": volume})
def f():
    pass

persist

def persist(
    self,
    label: str,
    namespace=api_pb2.DEPLOYMENT_NAMESPACE_WORKSPACE,
    environment_name: Optional[str] = None,
    cloud: Optional[str] = None,
):

NetworkFileSystem().persist("my-volume") is deprecated. Use NetworkFileSystem.persisted("my-volume") instead.

lookup

@staticmethod
def lookup(
    label: str,
    namespace=api_pb2.DEPLOYMENT_NAMESPACE_WORKSPACE,
    client: Optional[_Client] = None,
    environment_name: Optional[str] = None,
    create_if_missing: bool = False,
) -> "_NetworkFileSystem":

Lookup a network file system with a given name

n = modal.NetworkFileSystem.lookup("my-nfs")
print(n.listdir("/"))

write_file

@live_method
def write_file(self, remote_path: str, fp: BinaryIO) -> int:

Write from a file object to a path on the network file system, 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.

read_file

@live_method_gen
def read_file(self, path: str) -> Iterator[bytes]:

Read a file from the network file system

iterdir

@live_method_gen
def iterdir(self, path: str) -> Iterator[api_pb2.SharedVolumeListFilesEntry]:

Iterate over all files in a directory in the network file system.

  • 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)

add_local_file

@live_method
def add_local_file(
    self, local_path: Union[Path, str], remote_path: Optional[Union[str, PurePosixPath, None]] = None
):

add_local_dir

@live_method
def add_local_dir(
    self,
    local_path: Union[Path, str],
    remote_path: Optional[Union[str, PurePosixPath, None]] = None,
):

listdir

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

List all files in a directory in the network file system.

  • 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)

remove_file

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

Remove a file in a network file system.