modal 1.0.6.dev58__py3-none-any.whl → 1.2.3.dev7__py3-none-any.whl

modal/image.py

@@ -7,7 +7,7 @@ import shlex
 import sys
 import typing
 import warnings
-from collections.abc import Sequence
+from collections.abc import Collection, Sequence
 from dataclasses import dataclass
 from inspect import isfunction
 from pathlib import Path, PurePosixPath
@@ -25,20 +25,22 @@ from google.protobuf.message import Message
 from grpclib.exceptions import GRPCError, StreamTerminatedError
 from typing_extensions import Self
 
+from modal._serialization import serialize_data_format
 from modal_proto import api_pb2
 
+from ._load_context import LoadContext
 from ._object import _Object, live_method_gen
 from ._resolver import Resolver
-from ._serialization import serialize
+from ._serialization import get_preferred_payload_format, serialize
 from ._utils.async_utils import synchronize_api
 from ._utils.blob_utils import MAX_OBJECT_SIZE_BYTES
-from ._utils.deprecation import deprecation_warning
 from ._utils.docker_utils import (
     extract_copy_command_patterns,
     find_dockerignore_file,
 )
 from ._utils.function_utils import FunctionInfo
-from ._utils.grpc_utils import RETRYABLE_GRPC_STATUS_CODES, retry_transient_errors
+from ._utils.grpc_utils import RETRYABLE_GRPC_STATUS_CODES
+from ._utils.mount_utils import validate_only_modal_volumes
 from .client import _Client
 from .cloud_bucket_mount import _CloudBucketMount
 from .config import config, logger, user_config_path
@@ -71,7 +73,7 @@ SUPPORTED_PYTHON_SERIES: dict[ImageBuilderVersion, list[str]] = {
     "2023.12": ["3.9", "3.10", "3.11", "3.12"],
 }
 
-LOCAL_REQUIREMENTS_DIR = Path(__file__).parent / "requirements"
+LOCAL_REQUIREMENTS_DIR = Path(__file__).parent / "builder"
 CONTAINER_REQUIREMENTS_PATH = "/modal_requirements.txt"
 
 
@@ -283,24 +285,12 @@ def _create_context_mount_function(
     ignore: Union[Sequence[str], Callable[[Path], bool], _AutoDockerIgnoreSentinel],
     dockerfile_cmds: list[str] = [],
     dockerfile_path: Optional[Path] = None,
-    context_mount: Optional[_Mount] = None,
     context_dir: Optional[Union[Path, str]] = None,
 ):
     if dockerfile_path and dockerfile_cmds:
         raise InvalidError("Cannot provide both dockerfile and docker commands")
 
-    if context_mount:
-        if ignore is not AUTO_DOCKERIGNORE:
-            raise InvalidError("Cannot set both `context_mount` and `ignore`")
-        if context_dir is not None:
-            raise InvalidError("Cannot set both `context_mount` and `context_dir`")
-
-        def identity_context_mount_fn() -> Optional[_Mount]:
-            return context_mount
-
-        return identity_context_mount_fn
-
-    elif ignore is AUTO_DOCKERIGNORE:
+    if ignore is AUTO_DOCKERIGNORE:
 
         def auto_created_context_mount_fn() -> Optional[_Mount]:
             nonlocal context_dir
@@ -445,12 +435,16 @@ class _Image(_Object, type_prefix="im"):
 
         base_image = self
 
-        async def _load(self2: "_Image", resolver: Resolver, existing_object_id: Optional[str]):
+        async def _load(
+            self2: "_Image", resolver: Resolver, load_context: LoadContext, existing_object_id: Optional[str]
+        ):
             self2._hydrate_from_other(base_image)  # same image id as base image as long as it's lazy
             self2._deferred_mounts = tuple(base_image._deferred_mounts) + (mount,)
             self2._serve_mounts = base_image._serve_mounts | ({mount} if mount.is_local() else set())
 
-        img = _Image._from_loader(_load, "Image(local files)", deps=lambda: [base_image, mount])
+        img = _Image._from_loader(
+            _load, "Image(local files)", deps=lambda: [base_image, mount], load_context_overrides=LoadContext.empty()
+        )
         img._added_python_source_set = base_image._added_python_source_set
         return img
 
@@ -491,7 +485,7 @@ class _Image(_Object, type_prefix="im"):
         *,
         base_images: Optional[dict[str, "_Image"]] = None,
         dockerfile_function: Optional[Callable[[ImageBuilderVersion], DockerfileSpec]] = None,
-        secrets: Optional[Sequence[_Secret]] = None,
+        secrets: Optional[Collection[_Secret]] = None,
         gpu_config: Optional[api_pb2.GPUConfig] = None,
         build_function: Optional["modal._functions._Function"] = None,
         build_function_input: Optional[api_pb2.FunctionInput] = None,
@@ -499,6 +493,7 @@ class _Image(_Object, type_prefix="im"):
         context_mount_function: Optional[Callable[[], Optional[_Mount]]] = None,
         force_build: bool = False,
         build_args: dict[str, str] = {},
+        validated_volumes: Optional[Sequence[tuple[str, _Volume]]] = None,
         # For internal use only.
         _namespace: "api_pb2.DeploymentNamespace.ValueType" = api_pb2.DEPLOYMENT_NAMESPACE_WORKSPACE,
         _do_assert_no_mount_layers: bool = True,
@@ -506,6 +501,9 @@ class _Image(_Object, type_prefix="im"):
         if base_images is None:
             base_images = {}
 
+        if validated_volumes is None:
+            validated_volumes = []
+
         if secrets is None:
             secrets = []
         if gpu_config is None:
@@ -526,20 +524,22 @@ class _Image(_Object, type_prefix="im"):
                 deps += (build_function,)
             if image_registry_config and image_registry_config.secret:
                 deps += (image_registry_config.secret,)
+            for _, vol in validated_volumes:
+                deps += (vol,)
             return deps
 
-        async def _load(self: _Image, resolver: Resolver, existing_object_id: Optional[str]):
+        async def _load(self: _Image, resolver: Resolver, load_context: LoadContext, existing_object_id: Optional[str]):
             context_mount = context_mount_function() if context_mount_function else None
             if context_mount:
-                await resolver.load(context_mount)
+                await resolver.load(context_mount, load_context)
 
             if _do_assert_no_mount_layers:
                 for image in base_images.values():
                     # base images can't have
                     image._assert_no_mount_layers()
 
-            assert resolver.app_id  # type narrowing
-            environment = await _get_environment_cached(resolver.environment_name or "", resolver.client)
+            assert load_context.app_id  # type narrowing
+            environment = await _get_environment_cached(load_context.environment_name or "", load_context.client)
             # A bit hacky,but assume that the environment provides a valid builder version
             image_builder_version = cast(ImageBuilderVersion, environment._settings.image_builder_version)
             builder_version = _get_image_builder_version(image_builder_version)
@@ -604,6 +604,17 @@ class _Image(_Object, type_prefix="im"):
                 build_function_id = ""
                 _build_function = None
 
+            # Relies on dicts being ordered (true as of Python 3.6).
+            volume_mounts = [
+                api_pb2.VolumeMount(
+                    mount_path=path,
+                    volume_id=volume.object_id,
+                    allow_background_commits=True,
+                    read_only=volume._read_only,
+                )
+                for path, volume in validated_volumes
+            ]
+
             image_definition = api_pb2.Image(
                 base_images=base_images_pb2s,
                 dockerfile_commands=dockerfile.commands,
@@ -616,10 +627,11 @@ class _Image(_Object, type_prefix="im"):
                 runtime_debug=config.get("function_runtime_debug"),
                 build_function=_build_function,
                 build_args=build_args,
+                volume_mounts=volume_mounts,
             )
 
             req = api_pb2.ImageGetOrCreateRequest(
-                app_id=resolver.app_id,
+                app_id=load_context.app_id,
                 image=image_definition,
                 existing_image_id=existing_object_id or "",  # TODO: ignored
                 build_function_id=build_function_id,
@@ -631,7 +643,7 @@ class _Image(_Object, type_prefix="im"):
                 allow_global_deployment=os.environ.get("MODAL_IMAGE_ALLOW_GLOBAL_DEPLOYMENT") == "1",
                 ignore_cache=config.get("ignore_cache"),
             )
-            resp = await retry_transient_errors(resolver.client.stub.ImageGetOrCreate, req)
+            resp = await load_context.client.stub.ImageGetOrCreate(req)
             image_id = resp.image_id
             result: api_pb2.GenericResult
             metadata: Optional[api_pb2.ImageMetadata] = None
@@ -644,7 +656,7 @@ class _Image(_Object, type_prefix="im"):
             else:
                 # not built or in the process of building - wait for build
                 logger.debug("Waiting for image %s" % image_id)
-                resp = await _image_await_build_result(image_id, resolver.client)
+                resp = await _image_await_build_result(image_id, load_context.client)
                 result = resp.result
                 if resp.HasField("metadata"):
                     metadata = resp.metadata
@@ -658,7 +670,13 @@ class _Image(_Object, type_prefix="im"):
                         msg += " (Hint: Use `modal.enable_output()` to see logs from the process building the Image.)"
                     raise RemoteError(msg)
             elif result.status == api_pb2.GenericResult.GENERIC_STATUS_TERMINATED:
-                raise RemoteError(f"Image build for {image_id} terminated due to external shut-down. Please try again.")
+                msg = f"Image build for {image_id} terminated due to external shut-down. Please try again."
+                if result.exception:
+                    msg = (
+                        f"Image build for {image_id} terminated due to external shut-down with the exception:\n"
+                        f"{result.exception}"
+                    )
+                raise RemoteError(msg)
             elif result.status == api_pb2.GenericResult.GENERIC_STATUS_TIMEOUT:
                 raise RemoteError(
                     f"Image build for {image_id} timed out. Please try again with a larger `timeout` parameter."
@@ -668,7 +686,7 @@ class _Image(_Object, type_prefix="im"):
             else:
                 raise RemoteError("Unknown status %s!" % result.status)
 
-            self._hydrate(image_id, resolver.client, metadata)
+            self._hydrate(image_id, load_context.client, metadata)
             local_mounts = set()
             for base in base_images.values():
                 local_mounts |= base._serve_mounts
@@ -677,7 +695,7 @@ class _Image(_Object, type_prefix="im"):
             self._serve_mounts = frozenset(local_mounts)
 
         rep = f"Image({dockerfile_function})"
-        obj = _Image._from_loader(_load, rep, deps=_deps)
+        obj = _Image._from_loader(_load, rep, deps=_deps, load_context_overrides=LoadContext.empty())
         obj.force_build = force_build
         obj._added_python_source_set = frozenset.union(
             frozenset(), *(base._added_python_source_set for base in base_images.values())
@@ -850,18 +868,75 @@ class _Image(_Object, type_prefix="im"):
 
         The ID of an Image object can be accessed using `.object_id`.
         """
-        if client is None:
-            client = await _Client.from_env()
 
-        async def _load(self: _Image, resolver: Resolver, existing_object_id: Optional[str]):
-            resp = await retry_transient_errors(client.stub.ImageFromId, api_pb2.ImageFromIdRequest(image_id=image_id))
-            self._hydrate(resp.image_id, resolver.client, resp.metadata)
+        async def _load(self: _Image, resolver: Resolver, load_context: LoadContext, existing_object_id: Optional[str]):
+            resp = await load_context.client.stub.ImageFromId(api_pb2.ImageFromIdRequest(image_id=image_id))
+            self._hydrate(resp.image_id, load_context.client, resp.metadata)
 
         rep = f"Image.from_id({image_id!r})"
-        obj = _Image._from_loader(_load, rep)
+        obj = _Image._from_loader(_load, rep, load_context_overrides=LoadContext(client=client))
 
         return obj
 
+    async def build(self, app: "modal.app._App") -> "_Image":
+        """Eagerly build an image.
+
+        If your image was previously built, then this method will not rebuild your image
+        and your cached image is returned.
+
+        **Examples**
+
+        ```python
+        image = modal.Image.debian_slim().uv_pip_install("scipy", "numpy")
+
+        app = modal.App.lookup("build-image", create_if_missing=True)
+        with modal.enable_output():  # To see logs in your local terminal
+            image.build(app)
+
+        # Save the image id
+        my_image_id = image.object_id
+
+        # Reference the image with the id or uses it another context.
+        built_image = modal.Image.from_id(my_image_id)
+        ```
+
+        Alternatively, you can pre-build a image and use it in a sandbox.
+
+        ```python notest
+        app = modal.App.lookup("sandbox-example", create_if_missing=True)
+
+        with modal.enable_output():
+            image = modal.Image.debian_slim().uv_pip_install("scipy")
+            image.build(app)
+
+        sb = modal.Sandbox.create("python", "-c", "import scipy; print(scipy)", app=app, image=image)
+        print(sb.stdout.read())
+        sb.terminate()
+        ```
+
+        **Note**
+
+        For defining Modal functions, images are built automatically when deploying or running an App.
+        You do not need to built the image explicitly:
+
+        ```python notest
+        app = modal.App()
+        image = modal.Image.debian_slim()
+
+        # No need to explicitly build the image for defining a function.
+        @app.function(image=image)
+        def f():
+            ...
+        ```
+
+        """
+        if app.app_id is None:
+            raise InvalidError("App has not been initialized yet. Use the content manager `app.run()` or `App.lookup`")
+
+        resolver = Resolver()
+        await resolver.load(self, app._root_load_context)
+        return self
+
     def pip_install(
         self,
         *packages: Union[str, list[str]],  # A list of Python packages, eg. ["numpy", "matplotlib>=3.5.0"]
@@ -871,7 +946,8 @@ class _Image(_Object, type_prefix="im"):
         pre: bool = False,  # Passes --pre (allow pre-releases) to pip install
         extra_options: str = "",  # Additional options to pass to pip install, e.g. "--no-build-isolation --no-clean"
         force_build: bool = False,  # Ignore cached builds, similar to 'docker build --no-cache'
-        secrets: Sequence[_Secret] = [],
+        env: Optional[dict[str, Optional[str]]] = None,
+        secrets: Optional[Collection[_Secret]] = None,
         gpu: GPU_T = None,
     ) -> "_Image":
         """Install a list of Python packages using pip.
@@ -918,6 +994,10 @@ class _Image(_Object, type_prefix="im"):
                 commands = [cmd.strip() for cmd in commands]
             return DockerfileSpec(commands=commands, context_files={})
 
+        secrets = secrets or []
+        if env:
+            secrets = [*secrets, _Secret.from_dict(env)]
+
         gpu_config = parse_gpu_config(gpu)
         return _Image._from_args(
             base_images={"base": self},
@@ -937,7 +1017,8 @@ class _Image(_Object, type_prefix="im"):
         pre: bool = False,  # Passes --pre (allow pre-releases) to pip install
         extra_options: str = "",  # Additional options to pass to pip install, e.g. "--no-build-isolation --no-clean"
         gpu: GPU_T = None,
-        secrets: Sequence[_Secret] = [],
+        env: Optional[dict[str, Optional[str]]] = None,  # Environment variables to set in the container
+        secrets: Optional[Collection[_Secret]] = None,  # Secrets to inject into the container as environment variables
         force_build: bool = False,  # Ignore cached builds, similar to 'docker build --no-cache'
     ) -> "_Image":
         """
@@ -971,12 +1052,16 @@ class _Image(_Object, type_prefix="im"):
         )
         ```
         """
+
         if not secrets:
             raise InvalidError(
                 "No secrets provided to function. "
                 "Installing private packages requires tokens to be passed via modal.Secret objects."
             )
 
+        if env:
+            secrets = [*secrets, _Secret.from_dict(env)]
+
         invalid_repos = []
         install_urls = []
         for repo_ref in repositories:
@@ -1038,11 +1123,16 @@ class _Image(_Object, type_prefix="im"):
         pre: bool = False,  # Passes --pre (allow pre-releases) to pip install
         extra_options: str = "",  # Additional options to pass to pip install, e.g. "--no-build-isolation --no-clean"
         force_build: bool = False,  # Ignore cached builds, similar to 'docker build --no-cache'
-        secrets: Sequence[_Secret] = [],
+        env: Optional[dict[str, Optional[str]]] = None,
+        secrets: Optional[Collection[_Secret]] = None,
         gpu: GPU_T = None,
     ) -> "_Image":
         """Install a list of Python packages from a local `requirements.txt` file."""
 
+        secrets = secrets or []
+        if env:
+            secrets = [*secrets, _Secret.from_dict(env)]
+
         def build_dockerfile(version: ImageBuilderVersion) -> DockerfileSpec:
             requirements_txt_path = os.path.expanduser(requirements_txt)
             context_files = {"/.requirements.txt": requirements_txt_path}
@@ -1079,7 +1169,8 @@ class _Image(_Object, type_prefix="im"):
         pre: bool = False,  # Passes --pre (allow pre-releases) to pip install
         extra_options: str = "",  # Additional options to pass to pip install, e.g. "--no-build-isolation --no-clean"
         force_build: bool = False,  # Ignore cached builds, similar to 'docker build --no-cache'
-        secrets: Sequence[_Secret] = [],
+        env: Optional[dict[str, Optional[str]]] = None,
+        secrets: Optional[Collection[_Secret]] = None,
         gpu: GPU_T = None,
     ) -> "_Image":
         """Install dependencies specified by a local `pyproject.toml` file.
@@ -1090,6 +1181,10 @@ class _Image(_Object, type_prefix="im"):
         all of the packages in each listed section are installed as well.
         """
 
+        secrets = secrets or []
+        if env:
+            secrets = [*secrets, _Secret.from_dict(env)]
+
         def build_dockerfile(version: ImageBuilderVersion) -> DockerfileSpec:
             # Defer toml import so we don't need it in the container runtime environment
             import toml
@@ -1141,7 +1236,8 @@ class _Image(_Object, type_prefix="im"):
         extra_options: str = "",  # Additional options to pass to pip install, e.g. "--no-build-isolation"
         force_build: bool = False,  # Ignore cached builds, similar to 'docker build --no-cache'
         uv_version: Optional[str] = None,  # uv version to use
-        secrets: Sequence[_Secret] = [],
+        env: Optional[dict[str, Optional[str]]] = None,
+        secrets: Optional[Collection[_Secret]] = None,
         gpu: GPU_T = None,
     ) -> "_Image":
         """Install a list of Python packages using uv pip install.
@@ -1157,7 +1253,14 @@ class _Image(_Object, type_prefix="im"):
         - Python is on the `$PATH` and dependencies are installed with the first Python on the `$PATH`.
         - Shell supports backticks for substitution
         - `which` command is on the `$PATH`
+
+        Added in v1.1.0.
         """
+
+        secrets = secrets or []
+        if env:
+            secrets = [*secrets, _Secret.from_dict(env)]
+
         pkgs = _flatten_str_args("uv_pip_install", "packages", packages)
 
         if requirements is None or isinstance(requirements, list):
@@ -1181,11 +1284,11 @@ class _Image(_Object, type_prefix="im"):
             else:
                 commands.append(f"COPY --from=ghcr.io/astral-sh/uv:{uv_version} /uv {UV_ROOT}/uv")
 
-            # NOTE: Using `which python` assumes:
+            # NOTE: Using $(command -v python) assumes:
             # - python is on the PATH and uv is installing into the first python in the PATH
-            # - the shell supports backticks for substitution
-            # - `which` command is on the PATH
-            uv_pip_args = ["--python `which python`", "--compile-bytecode"]
+            # - the shell supports $() for substitution
+            # - `command` command is on the PATH
+            uv_pip_args = ["--python $(command -v python)", "--compile-bytecode"]
             context_files = {}
 
             if find_links:
@@ -1253,7 +1356,8 @@ class _Image(_Object, type_prefix="im"):
         poetry_version: Optional[str] = "latest",  # Version of poetry to install, or None to skip installation
         # If set to True, use old installer. See https://github.com/python-poetry/poetry/issues/3336
         old_installer: bool = False,
-        secrets: Sequence[_Secret] = [],
+        env: Optional[dict[str, Optional[str]]] = None,
+        secrets: Optional[Collection[_Secret]] = None,
         gpu: GPU_T = None,
     ) -> "_Image":
         """Install poetry *dependencies* specified by a local `pyproject.toml` file.
@@ -1269,6 +1373,10 @@ class _Image(_Object, type_prefix="im"):
         version, with versions 2024.10 and earlier limiting poetry to 1.x.
         """
 
+        secrets = secrets or []
+        if env:
+            secrets = [*secrets, _Secret.from_dict(env)]
+
         def build_dockerfile(version: ImageBuilderVersion) -> DockerfileSpec:
             context_files = {"/.pyproject.toml": os.path.expanduser(poetry_pyproject_toml)}
 
@@ -1338,7 +1446,8 @@ class _Image(_Object, type_prefix="im"):
         frozen: bool = True,  # If True, then we run `uv sync --frozen` when a uv.lock file is present
         extra_options: str = "",  # Extra options to pass to `uv sync`
         uv_version: Optional[str] = None,  # uv version to use
-        secrets: Sequence[_Secret] = [],
+        env: Optional[dict[str, Optional[str]]] = None,
+        secrets: Optional[Collection[_Secret]] = None,
         gpu: GPU_T = None,
     ) -> "_Image":
         """Creates a virtual environment with the dependencies in a uv managed project with `uv sync`.
@@ -1347,8 +1456,26 @@ class _Image(_Object, type_prefix="im"):
         ```python
         image = modal.Image.debian_slim().uv_sync()
         ```
+
+        The `pyproject.toml` and `uv.lock` in `uv_project_dir` are automatically added to the build context. The
+        `uv_project_dir` is relative to the current working directory of where `modal` is called.
+
+        NOTE: This does *not* install the project itself into the environment (this is equivalent to the
+        `--no-install-project` flag in the `uv sync` command) and you would be expected to add any local python source
+        files using `Image.add_local_python_source` or similar methods after this call.
+
+        This ensures that updates to your project code wouldn't require reinstalling third-party dependencies
+        after every change.
+
+        uv workspaces are currently not supported.
+
+        Added in v1.1.0.
         """
 
+        secrets = secrets or []
+        if env:
+            secrets = [*secrets, _Secret.from_dict(env)]
+
         def _normalize_items(items, name) -> list[str]:
             if items is None:
                 return []
@@ -1381,7 +1508,13 @@ class _Image(_Object, type_prefix="im"):
                 # a requirement in `uv.lock`
                 return
 
-            dependencies = pyproject_toml_content["project"]["dependencies"]
+            try:
+                dependencies = pyproject_toml_content["project"]["dependencies"]
+            except KeyError as e:
+                raise InvalidError(
+                    f"Invalid pyproject.toml file: missing key {e} in {pyproject_toml}. "
+                    "See https://packaging.python.org/en/latest/guides/writing-pyproject-toml for guidelines."
+                )
 
             for group in groups:
                 if (
@@ -1447,7 +1580,7 @@ class _Image(_Object, type_prefix="im"):
                 commands.append(f"COPY /.uv.lock {UV_ROOT}/uv.lock")
 
                 if frozen:
-                    # Do not update `uv.lock` when we have one when `frozen=True`. This it ehd efault because this
+                    # Do not update `uv.lock` when we have one when `frozen=True`. This is the default because this
                     # ensures that the runtime environment matches the local `uv.lock`.
                     #
                     # If `frozen=False`, then `uv sync` will update the the dependencies in the `uv.lock` file
@@ -1475,9 +1608,9 @@ class _Image(_Object, type_prefix="im"):
         self,
         *dockerfile_commands: Union[str, list[str]],
         context_files: dict[str, str] = {},
-        secrets: Sequence[_Secret] = [],
+        env: Optional[dict[str, Optional[str]]] = None,
+        secrets: Optional[Collection[_Secret]] = None,
         gpu: GPU_T = None,
-        context_mount: Optional[_Mount] = None,  # Deprecated: the context is now inferred
         context_dir: Optional[Union[Path, str]] = None,  # Context for relative COPY commands
         force_build: bool = False,  # Ignore cached builds, similar to 'docker build --no-cache'
         ignore: Union[Sequence[str], Callable[[Path], bool]] = AUTO_DOCKERIGNORE,
@@ -1523,16 +1656,14 @@ class _Image(_Object, type_prefix="im"):
         )
         ```
         """
-        if context_mount is not None:
-            deprecation_warning(
-                (2025, 1, 13),
-                "The `context_mount` parameter of `Image.dockerfile_commands` is deprecated."
-                " Files are now automatically added to the build context based on the commands.",
-            )
         cmds = _flatten_str_args("dockerfile_commands", "dockerfile_commands", dockerfile_commands)
         if not cmds:
             return self
 
+        secrets = secrets or []
+        if env:
+            secrets = [*secrets, _Secret.from_dict(env)]
+
         def build_dockerfile(version: ImageBuilderVersion) -> DockerfileSpec:
             return DockerfileSpec(commands=["FROM base", *cmds], context_files=context_files)
 
@@ -1542,7 +1673,7 @@ class _Image(_Object, type_prefix="im"):
             secrets=secrets,
             gpu_config=parse_gpu_config(gpu),
             context_mount_function=_create_context_mount_function(
-                ignore=ignore, dockerfile_cmds=cmds, context_mount=context_mount, context_dir=context_dir
+                ignore=ignore, dockerfile_cmds=cmds, context_dir=context_dir
             ),
             force_build=self.force_build or force_build,
         )
@@ -1551,7 +1682,7 @@ class _Image(_Object, type_prefix="im"):
         self,
         entrypoint_commands: list[str],
     ) -> "_Image":
-        """Set the entrypoint for the image."""
+        """Set the ENTRYPOINT for the image."""
         if not isinstance(entrypoint_commands, list) or not all(isinstance(x, str) for x in entrypoint_commands):
             raise InvalidError("entrypoint_commands must be a list of strings.")
         args_str = _flatten_str_args("entrypoint", "entrypoint_commands", entrypoint_commands)
@@ -1576,11 +1707,18 @@ class _Image(_Object, type_prefix="im"):
     def run_commands(
         self,
         *commands: Union[str, list[str]],
-        secrets: Sequence[_Secret] = [],
+        env: Optional[dict[str, Optional[str]]] = None,
+        secrets: Optional[Collection[_Secret]] = None,
+        volumes: Optional[dict[Union[str, PurePosixPath], _Volume]] = None,
         gpu: GPU_T = None,
         force_build: bool = False,  # Ignore cached builds, similar to 'docker build --no-cache'
     ) -> "_Image":
         """Extend an image with a list of shell commands to run."""
+
+        secrets = secrets or []
+        if env:
+            secrets = [*secrets, _Secret.from_dict(env)]
+
         cmds = _flatten_str_args("run_commands", "commands", commands)
         if not cmds:
             return self
@@ -1594,6 +1732,7 @@ class _Image(_Object, type_prefix="im"):
             secrets=secrets,
             gpu_config=parse_gpu_config(gpu),
             force_build=self.force_build or force_build,
+            validated_volumes=validate_only_modal_volumes(volumes, "Image.run_commands"),
         )
 
     @staticmethod
@@ -1639,10 +1778,16 @@ class _Image(_Object, type_prefix="im"):
         # A list of Conda channels, eg. ["conda-forge", "nvidia"].
         channels: list[str] = [],
         force_build: bool = False,  # Ignore cached builds, similar to 'docker build --no-cache'
-        secrets: Sequence[_Secret] = [],
+        env: Optional[dict[str, Optional[str]]] = None,
+        secrets: Optional[Collection[_Secret]] = None,
         gpu: GPU_T = None,
     ) -> "_Image":
         """Install a list of additional packages using micromamba."""
+
+        secrets = secrets or []
+        if env:
+            secrets = [*secrets, _Secret.from_dict(env)]
+
         pkgs = _flatten_str_args("micromamba_install", "packages", packages)
         if not pkgs and spec_file is None:
             return self
@@ -1844,12 +1989,18 @@ class _Image(_Object, type_prefix="im"):
     ) -> "_Image":
         """Build a Modal image from a private image in AWS Elastic Container Registry (ECR).
 
-        You will need to pass a `modal.Secret` containing `AWS_ACCESS_KEY_ID`,
-        `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION` to access the target ECR registry.
+        You will need to pass a `modal.Secret` containing either IAM user credentials or OIDC
+        configuration to access the target ECR registry.
+
+        For IAM user authentication, set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION`.
+
+        For OIDC authentication, set `AWS_ROLE_ARN` and `AWS_REGION`.
 
         IAM configuration details can be found in the AWS documentation for
         ["Private repository policies"](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-policies.html).
 
+        For more details on using an AWS role to access ECR, see the [OIDC integration guide](https://modal.com/docs/guide/oidc-integration).
+
         See `Image.from_registry()` for information about the other parameters.
 
         **Example**
@@ -1881,10 +2032,10 @@ class _Image(_Object, type_prefix="im"):
     def from_dockerfile(
         path: Union[str, Path],  # Filepath to Dockerfile.
         *,
-        context_mount: Optional[_Mount] = None,  # Deprecated: the context is now inferred
         force_build: bool = False,  # Ignore cached builds, similar to 'docker build --no-cache'
         context_dir: Optional[Union[Path, str]] = None,  # Context for relative COPY commands
-        secrets: Sequence[_Secret] = [],
+        env: Optional[dict[str, Optional[str]]] = None,
+        secrets: Optional[Collection[_Secret]] = None,
         gpu: GPU_T = None,
         add_python: Optional[str] = None,
         build_args: dict[str, str] = {},
@@ -1939,12 +2090,10 @@ class _Image(_Object, type_prefix="im"):
         )
         ```
         """
-        if context_mount is not None:
-            deprecation_warning(
-                (2025, 1, 13),
-                "The `context_mount` parameter of `Image.from_dockerfile` is deprecated."
-                " Files are now automatically added to the build context based on the commands in the Dockerfile.",
-            )
+
+        secrets = secrets or []
+        if env:
+            secrets = [*secrets, _Secret.from_dict(env)]
 
         # --- Build the base dockerfile
 
@@ -1957,7 +2106,7 @@ class _Image(_Object, type_prefix="im"):
         base_image = _Image._from_args(
             dockerfile_function=build_dockerfile_base,
             context_mount_function=_create_context_mount_function(
-                ignore=ignore, dockerfile_path=Path(path), context_mount=context_mount, context_dir=context_dir
+                ignore=ignore, dockerfile_path=Path(path), context_dir=context_dir
             ),
             gpu_config=gpu_config,
             secrets=secrets,
@@ -2053,7 +2202,8 @@ class _Image(_Object, type_prefix="im"):
         self,
         *packages: Union[str, list[str]],  # A list of packages, e.g. ["ssh", "libpq-dev"]
         force_build: bool = False,  # Ignore cached builds, similar to 'docker build --no-cache'
-        secrets: Sequence[_Secret] = [],
+        env: Optional[dict[str, Optional[str]]] = None,
+        secrets: Optional[Collection[_Secret]] = None,
         gpu: GPU_T = None,
     ) -> "_Image":
         """Install a list of Debian packages using `apt`.
@@ -2078,6 +2228,10 @@ class _Image(_Object, type_prefix="im"):
             ]
             return DockerfileSpec(commands=commands, context_files={})
 
+        secrets = secrets or []
+        if env:
+            secrets = [*secrets, _Secret.from_dict(env)]
+
         return _Image._from_args(
             base_images={"base": self},
             dockerfile_function=build_dockerfile,
@@ -2090,24 +2244,26 @@ class _Image(_Object, type_prefix="im"):
         self,
         raw_f: Callable[..., Any],
         *,
-        secrets: Sequence[_Secret] = (),  # Optional Modal Secret objects with environment variables for the container
-        gpu: Union[GPU_T, list[GPU_T]] = None,  # Requested GPU or or list of acceptable GPUs( e.g. ["A10", "A100"])
+        env: Optional[dict[str, Optional[str]]] = None,  # Environment variables to set in the container
+        secrets: Optional[Collection[_Secret]] = None,  # Secrets to inject into the container as environment variables
         volumes: dict[Union[str, PurePosixPath], Union[_Volume, _CloudBucketMount]] = {},  # Volume mount paths
         network_file_systems: dict[Union[str, PurePosixPath], _NetworkFileSystem] = {},  # NFS mount paths
+        gpu: Union[GPU_T, list[GPU_T]] = None,  # Requested GPU or or list of acceptable GPUs( e.g. ["A10", "A100"])
         cpu: Optional[float] = None,  # How many CPU cores to request. This is a soft limit.
         memory: Optional[int] = None,  # How much memory to request, in MiB. This is a soft limit.
-        timeout: Optional[int] = 60 * 60,  # Maximum execution time of the function in seconds.
-        force_build: bool = False,  # Ignore cached builds, similar to 'docker build --no-cache'
+        timeout: int = 60 * 60,  # Maximum execution time of the function in seconds.
         cloud: Optional[str] = None,  # Cloud provider to run the function on. Possible values are aws, gcp, oci, auto.
         region: Optional[Union[str, Sequence[str]]] = None,  # Region or regions to run the function on.
+        force_build: bool = False,  # Ignore cached builds, similar to 'docker build --no-cache'
         args: Sequence[Any] = (),  # Positional arguments to the function.
         kwargs: dict[str, Any] = {},  # Keyword arguments to the function.
-        include_source: Optional[bool] = None,
+        include_source: bool = True,  # Whether the builder container should have the Function's source added
     ) -> "_Image":
-        """Run user-defined function `raw_f` as an image build step. The function runs just like an ordinary Modal
-        function, and any kwargs accepted by `@app.function` (such as `Mount`s, `NetworkFileSystem`s,
-        and resource requests) can be supplied to it.
-        After it finishes execution, a snapshot of the resulting container file system is saved as an image.
+        """Run user-defined function `raw_f` as an image build step.
+
+        The function runs like an ordinary Modal Function, accepting a resource configuration and integrating
+        with Modal features like Secrets and Volumes. Unlike ordinary Modal Functions, any changes to the
+        filesystem state will be captured on container exit and saved as a new Image.
 
         **Note**
 
@@ -2131,6 +2287,11 @@ class _Image(_Object, type_prefix="im"):
         )
         ```
         """
+
+        secrets = secrets or []
+        if env:
+            secrets = [*secrets, _Secret.from_dict(env)]
+
         from ._functions import _Function
 
         if not callable(raw_f):
@@ -2160,13 +2321,19 @@ class _Image(_Object, type_prefix="im"):
             include_source=include_source,
         )
         if len(args) + len(kwargs) > 0:
-            args_serialized = serialize((args, kwargs))
+            data_format = get_preferred_payload_format()
+            args_serialized = serialize_data_format((args, kwargs), data_format)
+
             if len(args_serialized) > MAX_OBJECT_SIZE_BYTES:
                 raise InvalidError(
                     f"Arguments to `run_function` are too large ({len(args_serialized)} bytes). "
                     f"Maximum size is {MAX_OBJECT_SIZE_BYTES} bytes."
                 )
-            build_function_input = api_pb2.FunctionInput(args=args_serialized, data_format=api_pb2.DATA_FORMAT_PICKLE)
+
+            build_function_input = api_pb2.FunctionInput(
+                args=args_serialized,
+                data_format=data_format,
+            )
         else:
             build_function_input = None
         return _Image._from_args(
@@ -2226,7 +2393,9 @@ class _Image(_Object, type_prefix="im"):
         )
 
     def cmd(self, cmd: list[str]) -> "_Image":
-        """Set the default entrypoint argument (`CMD`) for the image.
+        """Set the default command (`CMD`) to run when a container is started.
+
+        Used with `modal.Sandbox`. Has no effect on `modal.Function`.
 
         **Example**