modal 1.4.2.dev14__tar.gz → 1.4.3.dev0__tar.gz

{modal-1.4.2.dev14 → modal-1.4.3.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modal
-Version: 1.4.2.dev14
+Version: 1.4.3.dev0
 Summary: Python client library for Modal
 Author-email: Modal Labs <support@modal.com>
 License-Expression: Apache-2.0

{modal-1.4.2.dev14 → modal-1.4.3.dev0}/modal/_utils/sandbox_fs_utils.py

@@ -18,6 +18,7 @@ from ..exception import (
     SandboxFilesystemIsADirectoryError,
     SandboxFilesystemNotADirectoryError,
     SandboxFilesystemNotFoundError,
+    SandboxFilesystemPathAlreadyExistsError,
     SandboxFilesystemPermissionError,
     ServiceError,
 )
@@ -188,6 +189,42 @@ def raise_remove_error(returncode: int, stderr: Union[str, bytes], remote_path:
     raise SandboxFilesystemError(f"Operation on '{remote_path}' failed with exit code {returncode}")
 
 
+def make_make_directory_command(remote_path: str, create_parents: bool) -> str:
+    """Build the JSON command string for a MakeDirectory operation.
+
+    The returned JSON must match the `Command` enum in the modal-sandbox-fs-tools
+    Rust crate (crates/modal-sandbox-fs-tools/src/lib.rs). Treat changes to
+    this schema like protobuf changes: fields must not be removed or renamed,
+    only added with backwards-compatible defaults.
+    """
+    return json.dumps({"MakeDirectory": {"path": remote_path, "parents": create_parents}})
+
+
+def raise_make_directory_error(returncode: int, stderr: Union[str, bytes], remote_path: str) -> NoReturn:
+    if payload := try_parse_error_payload(stderr):
+        logger.debug(
+            f"sandbox-fs-tools make_directory error: path={remote_path}, "
+            f"error_kind={payload.error_kind}, message={payload.message}, detail={payload.detail}"
+        )
+        if payload.error_kind == "NotFound":
+            raise SandboxFilesystemNotFoundError(f"{payload.message}: {remote_path}")
+        if payload.error_kind == "PathAlreadyExists":
+            raise SandboxFilesystemPathAlreadyExistsError(f"{payload.message}: {remote_path}")
+        if payload.error_kind == "NotDirectory":
+            raise SandboxFilesystemNotADirectoryError(f"{payload.message}: {remote_path}")
+        if payload.error_kind == "PermissionDenied":
+            raise SandboxFilesystemPermissionError(f"{payload.message}: {remote_path}")
+        if payload.error_kind == "NotSupported":
+            raise InvalidError(
+                f"{payload.message}: {remote_path} - this operation is not supported for CloudBucketMounts"
+            )
+        raise SandboxFilesystemError(payload.message)
+
+    if stderr_text := _stderr_to_text(stderr):
+        logger.debug(f"Unstructured modal-sandbox-fs-tools stderr: {stderr_text}")
+    raise SandboxFilesystemError(f"Operation on '{remote_path}' failed with exit code {returncode}")
+
+
 def validate_absolute_remote_path(remote_path: str, operation: str) -> None:
     if not PurePosixPath(remote_path).is_absolute():
         raise InvalidError(f"Sandbox.filesystem.{operation}() currently only supports absolute remote_path values")

modal-1.4.3.dev0/modal/cli/bootstrap.py

@@ -0,0 +1,136 @@
+# Copyright Modal Labs 2026
+import io
+import shutil
+import zipfile
+from pathlib import Path
+from typing import Optional
+
+import click
+import typer
+
+from modal._utils.async_utils import synchronizer
+from modal._utils.http_utils import _http_client_with_tls
+from modal.client import _Client
+from modal.config import logger
+from modal.output import OutputManager
+from modal_proto import api_pb2
+
+from .logo import GREEN, print_logo
+from .selector import Selector
+
+
+@synchronizer.create_blocking
+async def bootstrap(
+    name: Optional[str] = typer.Argument(None, help="The name of the template to load."),
+    output: str = typer.Option(".", "-o", "--output", help="Location for storing the template."),
+    force: bool = typer.Option(False, "--force", help="Overwrite the output directory if it already exists."),
+) -> None:
+    """Initialize a sample Modal App."""
+    client = await _Client.from_env()
+    resp = await client.stub.TemplateList(api_pb2.TemplateListRequest())
+    names = sorted([item.name for item in resp.items])
+
+    output_manager = OutputManager.get()
+    print_logo()
+
+    if name is None:
+        if not names:
+            output_manager.print("No templates available. Try updating modal.")
+            raise typer.Exit(1)
+        try:
+            selector = Selector(names, title="Select a template", highlight_style=f"bold {GREEN}")
+            name = selector.run()
+        except Exception:
+            output_manager.print("Available templates:")
+            for n in names:
+                output_manager.print(f"  - {n}")
+            output_manager.print("\nRun `modal bootstrap <name>` to select a template.")
+            raise typer.Exit(0)
+
+    item = next((item for item in resp.items if item.name == name), None)
+    if item is None:
+        output_manager.print(f"Unknown template: {name}")
+        output_manager.print(f"Available templates: {', '.join(names)}")
+        raise typer.Exit(1)
+
+    template_root = Path(output)
+    template_root.mkdir(parents=True, exist_ok=True)
+    template_written_to_cwd = template_root.resolve() == Path.cwd().resolve()
+
+    dest = template_root / name
+    if dest.exists() and not force:
+        raise click.UsageError(f"Output path '{dest}' already exists. Use --force to overwrite.")
+
+    # Download the repo archive
+    ref = item.ref or "main"
+    archive_url = item.repo.rstrip("/") + f"/archive/refs/heads/{ref}.zip"
+
+    with output_manager.status(f"Downloading template '{name}'..."):
+        try:
+            session = _http_client_with_tls(timeout=30)
+            try:
+                async with session.get(archive_url) as resp_http:
+                    resp_http.raise_for_status()
+                    data = await resp_http.read()
+            finally:
+                await session.close()
+        except Exception as e:
+            output_manager.print(f"Failed to download template from {archive_url}: {e}")
+            raise typer.Exit(1)
+
+    try:
+        zf = zipfile.ZipFile(io.BytesIO(data))
+        all_names = zf.namelist()
+        root_prefix = all_names[0].split("/")[0] + "/"
+    except Exception as e:
+        logger.debug(f"Failed to parse template archive: {e}")
+        output_manager.print(f"Unable to fetch template '{name}'.")
+        raise typer.Exit(1)
+
+    with zf:
+        template_prefix = root_prefix + name + "/"
+        logger.debug(f"Zip root: {root_prefix!r}, template: {template_prefix!r}, entries: {len(all_names)}")
+        for entry in all_names[:20]:
+            logger.debug(f"  {entry}")
+
+        members = [m for m in all_names if m.startswith(template_prefix) and m != template_prefix]
+        logger.debug(f"Matched {len(members)} members under {template_prefix!r}")
+
+        if not members:
+            output_manager.print(f"Template '{name}' not found in repository.")
+            raise typer.Exit(1)
+
+        if dest.exists() and force:
+            shutil.rmtree(dest)
+
+        dest.mkdir(parents=True, exist_ok=True)
+
+        resolved_dest = dest.resolve()
+        for member in members:
+            rel_path = member[len(template_prefix) :]
+            out_path = (dest / rel_path).resolve()
+            if not out_path.is_relative_to(resolved_dest):
+                logger.debug(f"Zip entry escapes destination: {member!r}")
+                output_manager.print(f"Unable to fetch template '{name}'.")
+                raise typer.Exit(1)
+            if member.endswith("/"):
+                out_path.mkdir(parents=True, exist_ok=True)
+            else:
+                out_path.parent.mkdir(parents=True, exist_ok=True)
+                out_path.write_bytes(zf.read(member))
+
+    output_manager.print(f"[{GREEN}]✓[/{GREEN}] Template '{name}' written to {dest}", highlight=False)
+    output_manager.print(f"[{GREEN}]→[/{GREEN}] To see it in action, run the following command:")
+    amp = " [dim white]&&[/dim white] "
+    if template_written_to_cwd:
+        steps = []
+    else:
+        steps = [f"[#ff8de6]cd {template_root}[/#ff8de6]"]
+    steps.extend(
+        [
+            f"[{GREEN}]modal deploy -m {name}.app[/{GREEN}]",
+            f"[#91c8ef]python -m {name}.try[/#91c8ef]",
+        ]
+    )
+    command = amp.join(steps)
+    output_manager.print(command)

{modal-1.4.2.dev14 → modal-1.4.3.dev0}/modal/cli/entry_point.py

@@ -11,6 +11,7 @@ from modal.output import OutputManager
 from . import run, shell as shell_module
 from .app import app_cli
 from .billing import billing_cli
+from .bootstrap import bootstrap
 from .changelog import changelog
 from .cluster import cluster_cli
 from .config import config_cli
@@ -19,6 +20,7 @@ from .dashboard import dashboard
 from .dict import dict_cli
 from .environment import environment_cli
 from .launch import launch_cli
+from .logo import print_logo
 from .network_file_system import nfs_cli
 from .profile import profile_cli
 from .queues import queue_cli
@@ -88,28 +90,7 @@ def check_path():
 @synchronizer.create_blocking
 async def setup(profile: Optional[str] = None):
     check_path()
-
-    art = """
-           #############        #############
-          ####         ##      ####         ##
-         ##  ##         ##    ##  ##         ##
-        ##    ##         ##  ##    ##         ##
-       ##      ##         ####      ##         ##
-      ##        #############        ##         ##
-     ##        ##         ####        ##         ##
-    ##        ##         ##  ##        ##         ##
-   ##        ##         ##    ##        ##         ##
-  ##        ##         ##      ##        ##         ##
- ##        ##         ##        ##        ##         ##
-##        ##         ##          ##        #############
- ##      ##         ##            ##      ##         ##
-  ##    ##         ##              ##    ##         ##
-   ##  ##         ##                ##  ##         ##
-    ####         ##                  ####         ##
-     #############                    #############
-"""
-
-    OutputManager.get().print(art, highlight=False, style="green")
+    print_logo()
 
     # Fetch a new token (same as `modal token new` but redirect to /home once finishes)
     await _new_token(profile=profile, next_url="/home")
@@ -145,8 +126,11 @@ entrypoint_cli_typer.add_typer(billing_cli, rich_help_panel="Observability")
 entrypoint_cli_typer.command("changelog", rich_help_panel="Observability")(changelog)
 entrypoint_cli_typer.command("dashboard", rich_help_panel="Observability")(dashboard)
 
-# Hide setup from help as it's redundant with modal token new, but nicer for onboarding
-entrypoint_cli_typer.command("setup", help="Bootstrap Modal's configuration.", rich_help_panel="Onboarding")(setup)
+# Onboarding
+entrypoint_cli_typer.command("setup", help="Get started using Modal.", rich_help_panel="Onboarding")(setup)
+entrypoint_cli_typer.command("bootstrap", help="Initialize a sample Modal App.", rich_help_panel="Onboarding")(
+    bootstrap
+)
 
 # Special handling for modal run, which is more complicated
 entrypoint_cli = typer.main.get_command(entrypoint_cli_typer)

modal-1.4.3.dev0/modal/cli/logo.py

@@ -0,0 +1,70 @@
+# Copyright Modal Labs 2026
+import sys
+
+from modal.output import OutputManager
+
+GREEN = "#7FEE64"
+
+ASCII_LOGO = """
+           #############        #############
+          ####         ##      ####         ##
+         ##  ##         ##    ##  ##         ##
+        ##    ##         ##  ##    ##         ##
+       ##      ##         ####      ##         ##
+      ##        #############        ##         ##
+     ##        ##         ####        ##         ##
+    ##        ##         ##  ##        ##         ##
+   ##        ##         ##    ##        ##         ##
+  ##        ##         ##      ##        ##         ##
+ ##        ##         ##        ##        ##         ##
+##        ##         ##          ##        #############
+ ##      ##         ##            ##      ##         ##
+  ##    ##         ##              ##    ##         ##
+   ##  ##         ##                ##  ##         ##
+    ####         ##                  ####         ##
+     #############                    #############
+"""
+
+UNICODE_LOGO_LARGE = """
+           █████████████        █████████████
+          ████         ██      ████         ██
+         ██  ██         ██    ██  ██         ██
+        ██    ██         ██  ██    ██         ██
+       ██      ██         ████      ██         ██
+      ██        █████████████        ██         ██
+     ██        ██         ████        ██         ██
+    ██        ██         ██  ██        ██         ██
+   ██        ██         ██    ██        ██         ██
+  ██        ██         ██      ██        ██         ██
+ ██        ██         ██        ██        ██         ██
+██        ██         ██          ██        █████████████
+ ██      ██         ██            ██      ██         ██
+  ██    ██         ██              ██    ██         ██
+   ██  ██         ██                ██  ██         ██
+    ████         ██                  ████         ██
+     █████████████                    █████████████
+"""
+
+UNICODE_LOGO_SMALL = """
+     ▟█▀▀▀▀▜▖  ▗█▛▀▀▀▀▙
+    ▟▘▝▙    ▜▖▗▛ ▜▖   ▝▙
+   ▟▘  ▝▙▄▄▄▄█▛   ▜▖   ▝▙
+  ▟▘   ▟▘   ▗▛▜▖   ▜▖   ▝▙
+ ▟▘   ▟▘   ▗▛  ▜▖   ▜▖   ▝▙
+▟▘   ▟▘   ▗▛    ▜▖   ▜▄▄▄▄▟▙
+▝▙  ▟▘   ▗▛      ▜▖ ▗▛    ▟▘
+ ▝▙▟▘   ▗▛        ▜▄▛    ▟▘
+  ▝▀▀▀▀▀▀          ▀▀▀▀▀▀▘
+"""
+
+
+def get_logo():
+    if sys.stdout.encoding and sys.stdout.encoding.lower().startswith("utf"):
+        return UNICODE_LOGO_SMALL
+    else:
+        return ASCII_LOGO
+
+
+def print_logo():
+    if sys.stdout.isatty():
+        OutputManager.get().print(get_logo(), highlight=False, style=GREEN)

{modal-1.4.2.dev14 → modal-1.4.3.dev0}/modal/cli/selector.py

@@ -19,6 +19,13 @@ def _cbreak_terminal():
     old_settings = termios.tcgetattr(fd)
     try:
         tty.setcbreak(fd, termios.TCSADRAIN)
+        # Disable ISIG so Ctrl-C is delivered as \x03 to os.read() rather than
+        # generating an asynchronous SIGINT. This lets _input_loop raise
+        # KeyboardInterrupt synchronously, ensuring context-manager cleanup
+        # (cursor visibility, terminal echo) completes without interruption.
+        attrs = termios.tcgetattr(fd)
+        attrs[3] &= ~termios.ISIG
+        termios.tcsetattr(fd, termios.TCSADRAIN, attrs)
         yield
     finally:
         termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
@@ -44,10 +51,10 @@ class Selector:
     exiting.
     """
 
-    def __init__(self, options: list[str], title: str = "Select an option"):
+    def __init__(self, options: list[str], title: str = "Select an option", highlight_style: str = "bold green"):
         if not options:
             raise ValueError("options must not be empty")
-        if not sys.stdin.isatty() or not sys.stdout.isatty():
+        if not sys.stdin.isatty() or not sys.stdout.isatty() or Console().is_dumb_terminal:
             raise RuntimeError("Interactive selection requires a TTY")
         # Fail fast on platforms without termios (e.g. Windows).
         import termios  # noqa: F401
@@ -55,6 +62,7 @@ class Selector:
         self.options = options
         self.title = title
         self.selected = 0
+        self.highlight_style = highlight_style
 
     # -- state manipulation ---------------------------------------------------
 
@@ -75,8 +83,8 @@ class Selector:
         text.append(f"{self.title}\n\n", style="bold")
         for i, opt in enumerate(self.options):
             if i == self.selected:
-                text.append("  > ", style="bold green")
-                text.append(f"{opt}\n", style="bold green")
+                text.append("  > ", style=self.highlight_style)
+                text.append(f"{opt}\n", style=self.highlight_style)
             else:
                 text.append(f"    {opt}\n")
         return text

{modal-1.4.2.dev14 → modal-1.4.3.dev0}/modal/client.pyi

@@ -35,7 +35,7 @@ class _Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.4.2.dev14",
+        version: str = "1.4.3.dev0",
     ):
         """mdmd:hidden
         The Modal client object is not intended to be instantiated directly by users.
@@ -175,7 +175,7 @@ class Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.4.2.dev14",
+        version: str = "1.4.3.dev0",
     ):
         """mdmd:hidden
         The Modal client object is not intended to be instantiated directly by users.

{modal-1.4.2.dev14 → modal-1.4.3.dev0}/modal/exception.py

@@ -379,3 +379,9 @@ class SandboxFilesystemFileTooLargeError(SandboxFilesystemError):
     """Raised when a file exceeds the maximum allowed size for a read operation in the sandbox."""
 
     pass
+
+
+class SandboxFilesystemPathAlreadyExistsError(SandboxFilesystemError):
+    """Raised when a path already exists and the operation requires it to be absent."""
+
+    pass

{modal-1.4.2.dev14 → modal-1.4.3.dev0}/modal/file_io.py

@@ -406,7 +406,7 @@ class _FileIO(Generic[T]):
         """Create a new directory."""
         deprecation_warning(
             (2026, 3, 9),
-            "`FileIO.mkdir()` is deprecated. Use `Sandbox.mkdir()` instead.",
+            "`FileIO.mkdir()` is deprecated. Use `Sandbox.filesystem.make_directory()` instead.",
             pending=True,
         )
         await mkdir(path, client, task_id, parents)
@@ -416,7 +416,7 @@ class _FileIO(Generic[T]):
         """Remove a file or directory in the Sandbox."""
         deprecation_warning(
             (2026, 3, 9),
-            "`FileIO.rm()` is deprecated. Use `Sandbox.rm()` instead.",
+            "`FileIO.rm()` is deprecated. Use `Sandbox.filesystem.remove()` instead.",
             pending=True,
         )
         await rm(path, client, task_id, recursive)

{modal-1.4.2.dev14 → modal-1.4.3.dev0}/modal/functions.pyi

@@ -347,7 +347,7 @@ class Function(
 
     _call_generator: ___call_generator_spec
 
-    class __remote_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER]):
+    class __remote_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> ReturnType_INNER:
             """Calls the function remotely, executing it with the given arguments and returning the execution's result."""
             ...
@@ -356,7 +356,7 @@ class Function(
             """Calls the function remotely, executing it with the given arguments and returning the execution's result."""
             ...
 
-    remote: __remote_spec[modal._functions.P, modal._functions.ReturnType]
+    remote: __remote_spec[modal._functions.ReturnType, modal._functions.P]
 
     class __remote_gen_spec(typing_extensions.Protocol):
         def __call__(self, /, *args, **kwargs) -> typing.Generator[typing.Any, None, None]:
@@ -383,7 +383,7 @@ class Function(
         """
         ...
 
-    class ___experimental_spawn_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER]):
+    class ___experimental_spawn_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> FunctionCall[ReturnType_INNER]:
             """[Experimental] Calls the function with the given arguments, without waiting for the results.
 
@@ -406,7 +406,7 @@ class Function(
             """
             ...
 
-    _experimental_spawn: ___experimental_spawn_spec[modal._functions.P, modal._functions.ReturnType]
+    _experimental_spawn: ___experimental_spawn_spec[modal._functions.ReturnType, modal._functions.P]
 
     class ___spawn_map_inner_spec(typing_extensions.Protocol[P_INNER]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> None: ...
@@ -414,7 +414,7 @@ class Function(
 
     _spawn_map_inner: ___spawn_map_inner_spec[modal._functions.P]
 
-    class __spawn_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER]):
+    class __spawn_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> FunctionCall[ReturnType_INNER]:
             """Calls the function with the given arguments, without waiting for the results.
 
@@ -435,7 +435,7 @@ class Function(
             """
             ...
 
-    spawn: __spawn_spec[modal._functions.P, modal._functions.ReturnType]
+    spawn: __spawn_spec[modal._functions.ReturnType, modal._functions.P]
 
     def get_raw_f(self) -> collections.abc.Callable[..., typing.Any]:
         """Return the inner Python object wrapped by this Modal Function."""

{modal-1.4.2.dev14 → modal-1.4.3.dev0}/modal/sandbox.py

@@ -1647,14 +1647,32 @@ class _Sandbox(_Object, type_prefix="sb"):
         return await ls(path, self._client, task_id)
 
     async def mkdir(self, path: str, parents: bool = False) -> None:
-        """[Alpha] Create a new directory in the Sandbox."""
+        """[Alpha] Create a new directory in the Sandbox.
+
+        .. deprecated:: 2026-04-15
+            Use `Sandbox.filesystem.make_directory()` instead.
+        """
         self._ensure_v1("mkdir")
+        deprecation_warning(
+            (2026, 4, 15),
+            "`Sandbox.mkdir()` is deprecated. Use `Sandbox.filesystem.make_directory()` instead.",
+            pending=True,
+        )
         task_id = await self._get_task_id()
         return await mkdir(path, self._client, task_id, parents)
 
     async def rm(self, path: str, recursive: bool = False) -> None:
-        """[Alpha] Remove a file or directory in the Sandbox."""
+        """[Alpha] Remove a file or directory in the Sandbox.
+
+        .. deprecated:: 2026-04-15
+            Use `Sandbox.filesystem.remove()` instead.
+        """
         self._ensure_v1("rm")
+        deprecation_warning(
+            (2026, 4, 15),
+            "`Sandbox.rm()` is deprecated. Use `Sandbox.filesystem.remove()` instead.",
+            pending=True,
+        )
         task_id = await self._get_task_id()
         return await rm(path, self._client, task_id, recursive)
 

{modal-1.4.2.dev14 → modal-1.4.3.dev0}/modal/sandbox.pyi

@@ -617,11 +617,19 @@ class _Sandbox(modal._object._Object):
         ...
 
     async def mkdir(self, path: str, parents: bool = False) -> None:
-        """[Alpha] Create a new directory in the Sandbox."""
+        """[Alpha] Create a new directory in the Sandbox.
+
+        .. deprecated:: 2026-04-15
+            Use `Sandbox.filesystem.make_directory()` instead.
+        """
         ...
 
     async def rm(self, path: str, recursive: bool = False) -> None:
-        """[Alpha] Remove a file or directory in the Sandbox."""
+        """[Alpha] Remove a file or directory in the Sandbox.
+
+        .. deprecated:: 2026-04-15
+            Use `Sandbox.filesystem.remove()` instead.
+        """
         ...
 
     def watch(
@@ -1911,22 +1919,38 @@ class Sandbox(modal.object.Object):
 
     class __mkdir_spec(typing_extensions.Protocol):
         def __call__(self, /, path: str, parents: bool = False) -> None:
-            """[Alpha] Create a new directory in the Sandbox."""
+            """[Alpha] Create a new directory in the Sandbox.
+
+            .. deprecated:: 2026-04-15
+                Use `Sandbox.filesystem.make_directory()` instead.
+            """
             ...
 
         async def aio(self, /, path: str, parents: bool = False) -> None:
-            """[Alpha] Create a new directory in the Sandbox."""
+            """[Alpha] Create a new directory in the Sandbox.
+
+            .. deprecated:: 2026-04-15
+                Use `Sandbox.filesystem.make_directory()` instead.
+            """
             ...
 
     mkdir: __mkdir_spec
 
     class __rm_spec(typing_extensions.Protocol):
         def __call__(self, /, path: str, recursive: bool = False) -> None:
-            """[Alpha] Remove a file or directory in the Sandbox."""
+            """[Alpha] Remove a file or directory in the Sandbox.
+
+            .. deprecated:: 2026-04-15
+                Use `Sandbox.filesystem.remove()` instead.
+            """
             ...
 
         async def aio(self, /, path: str, recursive: bool = False) -> None:
-            """[Alpha] Remove a file or directory in the Sandbox."""
+            """[Alpha] Remove a file or directory in the Sandbox.
+
+            .. deprecated:: 2026-04-15
+                Use `Sandbox.filesystem.remove()` instead.
+            """
             ...
 
     rm: __rm_spec

{modal-1.4.2.dev14 → modal-1.4.3.dev0}/modal/sandbox_fs.py

@@ -11,9 +11,11 @@ from typing import Union, cast
 from ._utils.async_utils import synchronize_api
 from ._utils.logger import logger
 from ._utils.sandbox_fs_utils import (
+    make_make_directory_command,
     make_read_file_command,
     make_remove_command,
     make_write_file_command,
+    raise_make_directory_error,
     raise_read_file_error,
     raise_remove_error,
     raise_write_file_error,
@@ -338,7 +340,7 @@ class _SandboxFilesystem:
         To remove a directory and all its contents:
 
         ```python fixture:sandbox
-        sandbox.exec("mkdir", "-p", "/tmp/mydir/subdir").wait()
+        sandbox.filesystem.make_directory("/tmp/mydir/subdir")
         sandbox.filesystem.remove("/tmp/mydir", recursive=True)
         ```
         """
@@ -351,5 +353,40 @@ class _SandboxFilesystem:
         if returncode != 0:
             raise_remove_error(returncode, stderr, remote_path)
 
+    async def make_directory(self, remote_path: str, *, create_parents: bool = True) -> None:
+        """Create a new directory in the Sandbox.
+
+        `remote_path` must be an absolute path in the Sandbox.
+
+        When `create_parents` is `True` (the default), any missing parent directories are created and the call is
+        idempotent (succeeds silently if the directory already exists). When `create_parents` is `False`, the
+        immediate parent directory must already exist and the path must not already exist.
+
+        **Raises**
+
+        - `SandboxFilesystemNotFoundError`: the parent directory does not exist and `create_parents` is `False`.
+        - `SandboxFilesystemPathAlreadyExistsError`: the path already exists.
+        - `SandboxFilesystemNotADirectoryError`: a path component is not a directory.
+        - `SandboxFilesystemPermissionError`: creation is not permitted.
+        - `InvalidError`: the operation is not supported by the mount.
+        - `SandboxFilesystemError`: the command fails for any other reason.
+
+        **Usage**
+
+        ```python fixture:sandbox
+        sandbox.filesystem.make_directory("/tmp/a/b/c")
+        ```
+        """
+        validate_absolute_remote_path(remote_path, "make_directory")
+
+        with translate_exec_errors("make_directory", remote_path):
+            process = await self._sandbox.exec(
+                _SANDBOX_FS_TOOLS_PATH, make_make_directory_command(remote_path, create_parents)
+            )
+            stderr, returncode = await asyncio.gather(process.stderr.read(), process.wait())
+
+        if returncode != 0:
+            raise_make_directory_error(returncode, stderr, remote_path)
+
 
 SandboxFilesystem = synchronize_api(_SandboxFilesystem)