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

nfs = modal.NetworkFileSystem.from_name("my-nfs", create_if_missing=True)
app = modal.App()

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

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

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.:

nfs = modal.NetworkFileSystem.lookup("my-network-file-system")
for chunk in nfs.read_file("my_db_dump.csv"):
    ...

def __init__(self, *args, **kwargs):

from_name

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

Reference a NetworkFileSystem by its name, creating if necessary.

In contrast to modal.NetworkFileSystem.lookup, this is a lazy method that defers hydrating the local object with metadata from Modal servers until the first time it is actually used.

nfs = NetworkFileSystem.from_name("my-nfs", create_if_missing=True)

@app.function(network_file_systems={"/data": nfs})
def f():
    pass

ephemeral

@classmethod
@contextmanager
def ephemeral(
    cls: type["_NetworkFileSystem"],
    client: Optional[_Client] = None,
    environment_name: Optional[str] = None,
    _heartbeat_sleep: float = EPHEMERAL_OBJECT_HEARTBEAT_SLEEP,
) -> Iterator["_NetworkFileSystem"]:

Creates a new ephemeral network filesystem within a context manager:

Usage:

with modal.NetworkFileSystem.ephemeral() as nfs:
    assert nfs.listdir("/") == []

async with modal.NetworkFileSystem.ephemeral() as nfs:
    assert await nfs.listdir("/") == []

lookup

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

Lookup a named NetworkFileSystem.

In contrast to modal.NetworkFileSystem.from_name, this is an eager method that will hydrate the local object with metadata from Modal servers.

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

delete

@staticmethod
@renamed_parameter((2024, 12, 18), "label", "name")
def delete(name: str, client: Optional[_Client] = None, environment_name: Optional[str] = None):

write_file

@live_method
def write_file(self, remote_path: str, fp: BinaryIO, progress_cb: Optional[Callable[..., Any]] = None) -> 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[FileEntry]:

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,
    progress_cb: Optional[Callable[..., Any]] = None,
):

add_local_dir

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

listdir

@live_method
def listdir(self, path: str) -> list[FileEntry]:

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.