modal 1.0.3.dev10__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
@@ -23,26 +23,29 @@ from typing import (
 
 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
 from .environments import _get_environment_cached
-from .exception import InvalidError, NotFoundError, RemoteError, VersionError
+from .exception import ExecutionError, InvalidError, NotFoundError, RemoteError, VersionError
 from .file_pattern_matcher import NON_PYTHON_FILES, FilePatternMatcher, _ignore_fn
 from .gpu import GPU_T, parse_gpu_config
 from .mount import _Mount, python_standalone_mount_name
@@ -56,7 +59,7 @@ if typing.TYPE_CHECKING:
     import modal._functions
 
 # This is used for both type checking and runtime validation
-ImageBuilderVersion = Literal["2023.12", "2024.04", "2024.10", "PREVIEW"]
+ImageBuilderVersion = Literal["2023.12", "2024.04", "2024.10", "2025.06", "PREVIEW"]
 
 # Note: we also define supported Python versions via logic at the top of the package __init__.py
 # so that we fail fast / clearly in unsupported containers. Additionally, we enumerate the supported
@@ -64,12 +67,13 @@ ImageBuilderVersion = Literal["2023.12", "2024.04", "2024.10", "PREVIEW"]
 # Consider consolidating these multiple sources of truth?
 SUPPORTED_PYTHON_SERIES: dict[ImageBuilderVersion, list[str]] = {
     "PREVIEW": ["3.9", "3.10", "3.11", "3.12", "3.13"],
+    "2025.06": ["3.9", "3.10", "3.11", "3.12", "3.13"],
     "2024.10": ["3.9", "3.10", "3.11", "3.12", "3.13"],
     "2024.04": ["3.9", "3.10", "3.11", "3.12"],
     "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"
 
 
@@ -281,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
@@ -416,7 +408,6 @@ class _Image(_Object, type_prefix="im"):
         self.force_build = False
 
     def _initialize_from_other(self, other: "_Image"):
-        # used by .clone()
         self.inside_exceptions = other.inside_exceptions
         self.force_build = other.force_build
         self._serve_mounts = other._serve_mounts
@@ -444,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
 
@@ -490,13 +485,15 @@ 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,
         image_registry_config: Optional[_ImageRegistryConfig] = None,
         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,
@@ -504,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:
@@ -524,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)
@@ -602,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,
@@ -613,10 +626,12 @@ class _Image(_Object, type_prefix="im"):
                 runtime=config.get("function_runtime"),
                 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,
@@ -628,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
@@ -641,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
@@ -655,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."
@@ -665,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
@@ -674,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())
@@ -797,28 +818,6 @@ class _Image(_Object, type_prefix="im"):
         mount = _Mount._add_local_dir(Path(local_path), PurePosixPath(remote_path), ignore=_ignore_fn(ignore))
         return self._add_mount_layer_or_copy(mount, copy=copy)
 
-    def copy_local_file(self, local_path: Union[str, Path], remote_path: Union[str, Path] = "./") -> "_Image":
-        """mdmd:hidden
-        Copy a file into the image as a part of building it.
-
-        This works in a similar way to [`COPY`](https://docs.docker.com/engine/reference/builder/#copy)
-        works in a `Dockerfile`.
-        """
-        deprecation_warning(
-            (2025, 1, 13),
-            COPY_DEPRECATION_MESSAGE_PATTERN.format(replacement="image.add_local_file"),
-        )
-        basename = str(Path(local_path).name)
-
-        def build_dockerfile(version: ImageBuilderVersion) -> DockerfileSpec:
-            return DockerfileSpec(commands=["FROM base", f"COPY {basename} {remote_path}"], context_files={})
-
-        return _Image._from_args(
-            base_images={"base": self},
-            dockerfile_function=build_dockerfile,
-            context_mount_function=lambda: _Mount._from_local_file(local_path, remote_path=f"/{basename}"),
-        )
-
     def add_local_python_source(
         self, *modules: str, copy: bool = False, ignore: Union[Sequence[str], Callable[[Path], bool]] = NON_PYTHON_FILES
     ) -> "_Image":
@@ -863,95 +862,80 @@ class _Image(_Object, type_prefix="im"):
         img._added_python_source_set |= set(modules)
         return img
 
-    def copy_local_dir(
-        self,
-        local_path: Union[str, Path],
-        remote_path: Union[str, Path] = ".",
-        # Predicate filter function for file exclusion, which should accept a filepath and return `True` for exclusion.
-        # Defaults to excluding no files. If a Sequence is provided, it will be converted to a FilePatternMatcher.
-        # Which follows dockerignore syntax.
-        ignore: Union[Sequence[str], Callable[[Path], bool]] = [],
-    ) -> "_Image":
-        """mdmd:hidden
-        **Deprecated**: Use image.add_local_dir instead
+    @staticmethod
+    async def from_id(image_id: str, client: Optional[_Client] = None) -> "_Image":
+        """Construct an Image from an id and look up the Image result.
 
-        Copy a directory into the image as a part of building the image.
+        The ID of an Image object can be accessed using `.object_id`.
+        """
 
-        This works in a similar way to [`COPY`](https://docs.docker.com/engine/reference/builder/#copy)
-        works in a `Dockerfile`.
+        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)
 
-        **Usage:**
+        rep = f"Image.from_id({image_id!r})"
+        obj = _Image._from_loader(_load, rep, load_context_overrides=LoadContext(client=client))
 
-        ```python notest
-        from pathlib import Path
-        from modal import FilePatternMatcher
+        return obj
 
-        image = modal.Image.debian_slim().copy_local_dir(
-            "~/assets",
-            remote_path="/assets",
-            ignore=["**/*.venv"],
-        )
+    async def build(self, app: "modal.app._App") -> "_Image":
+        """Eagerly build an image.
 
-        image = modal.Image.debian_slim().copy_local_dir(
-            "~/assets",
-            remote_path="/assets",
-            ignore=lambda p: p.is_relative_to(".venv"),
-        )
+        If your image was previously built, then this method will not rebuild your image
+        and your cached image is returned.
 
-        image = modal.Image.debian_slim().copy_local_dir(
-            "~/assets",
-            remote_path="/assets",
-            ignore=FilePatternMatcher("**/*.txt"),
-        )
+        **Examples**
 
-        # When including files is simpler than excluding them, you can use the `~` operator to invert the matcher.
-        image = modal.Image.debian_slim().copy_local_dir(
-            "~/assets",
-            remote_path="/assets",
-            ignore=~FilePatternMatcher("**/*.py"),
-        )
+        ```python
+        image = modal.Image.debian_slim().uv_pip_install("scipy", "numpy")
 
-        # You can also read ignore patterns from a file.
-        image = modal.Image.debian_slim().copy_local_dir(
-            "~/assets",
-            remote_path="/assets",
-            ignore=FilePatternMatcher.from_file("/path/to/ignorefile"),
-        )
+        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)
         ```
-        """
-        deprecation_warning(
-            (2025, 1, 13),
-            COPY_DEPRECATION_MESSAGE_PATTERN.format(replacement="image.add_local_dir"),
-        )
 
-        def build_dockerfile(version: ImageBuilderVersion) -> DockerfileSpec:
-            return DockerfileSpec(commands=["FROM base", f"COPY . {remote_path}"], context_files={})
+        Alternatively, you can pre-build a image and use it in a sandbox.
 
-        return _Image._from_args(
-            base_images={"base": self},
-            dockerfile_function=build_dockerfile,
-            context_mount_function=lambda: _Mount._add_local_dir(
-                Path(local_path), PurePosixPath("/"), ignore=_ignore_fn(ignore)
-            ),
-        )
+        ```python notest
+        app = modal.App.lookup("sandbox-example", create_if_missing=True)
 
-    @staticmethod
-    async def from_id(image_id: str, client: Optional[_Client] = None) -> "_Image":
-        """Construct an Image from an id and look up the Image result.
+        with modal.enable_output():
+            image = modal.Image.debian_slim().uv_pip_install("scipy")
+            image.build(app)
 
-        The ID of an Image object can be accessed using `.object_id`.
-        """
-        if client is None:
-            client = await _Client.from_env()
+        sb = modal.Sandbox.create("python", "-c", "import scipy; print(scipy)", app=app, image=image)
+        print(sb.stdout.read())
+        sb.terminate()
+        ```
 
-        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)
+        **Note**
 
-        rep = f"Image.from_id({image_id!r})"
-        obj = _Image._from_loader(_load, rep)
+        For defining Modal functions, images are built automatically when deploying or running an App.
+        You do not need to built the image explicitly:
 
-        return obj
+        ```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,
@@ -962,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.
@@ -1009,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},
@@ -1028,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":
         """
@@ -1062,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:
@@ -1129,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}
@@ -1170,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.
@@ -1181,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
@@ -1221,21 +1225,139 @@ class _Image(_Object, type_prefix="im"):
             gpu_config=parse_gpu_config(gpu),
         )
 
+    def uv_pip_install(
+        self,
+        *packages: Union[str, list[str]],  # A list of Python packages, eg. ["numpy", "matplotlib>=3.5.0"]
+        requirements: Optional[list[str]] = None,  # Passes -r (--requirements) to uv pip install
+        find_links: Optional[str] = None,  # Passes -f (--find-links) to uv pip install
+        index_url: Optional[str] = None,  # Passes -i (--index-url) to uv pip install
+        extra_index_url: Optional[str] = None,  # Passes --extra-index-url to uv pip install
+        pre: bool = False,  # Allow pre-releases using uv pip install --prerelease allow
+        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
+        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.
+
+        **Examples**
+
+        Simple installation:
+        ```python
+        image = modal.Image.debian_slim().uv_pip_install("torch==2.7.1", "numpy")
+        ```
+
+        This method assumes that:
+        - 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):
+            requirements = requirements or []
+        else:
+            raise InvalidError("requirements must be None or a list of strings")
+
+        if not pkgs and not requirements:
+            return self
+        elif not _validate_packages(pkgs):
+            raise InvalidError(
+                "Package list for `Image.uv_pip_install` cannot contain other arguments;"
+                " try the `extra_options` parameter instead."
+            )
+
+        def build_dockerfile(version: ImageBuilderVersion) -> DockerfileSpec:
+            commands = ["FROM base"]
+            UV_ROOT = "/.uv"
+            if uv_version is None:
+                commands.append(f"COPY --from=ghcr.io/astral-sh/uv:latest /uv {UV_ROOT}/uv")
+            else:
+                commands.append(f"COPY --from=ghcr.io/astral-sh/uv:{uv_version} /uv {UV_ROOT}/uv")
+
+            # 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 $() for substitution
+            # - `command` command is on the PATH
+            uv_pip_args = ["--python $(command -v python)", "--compile-bytecode"]
+            context_files = {}
+
+            if find_links:
+                uv_pip_args.append(f"--find-links {shlex.quote(find_links)}")
+            if index_url:
+                uv_pip_args.append(f"--index-url {shlex.quote(index_url)}")
+            if extra_index_url:
+                uv_pip_args.append(f"--extra-index-url {shlex.quote(extra_index_url)}")
+            if pre:
+                uv_pip_args.append("--prerelease allow")
+            if extra_options:
+                uv_pip_args.append(extra_options)
+
+            if requirements:
+
+                def _generate_paths(idx: int, req: str) -> dict:
+                    local_path = os.path.expanduser(req)
+                    basename = os.path.basename(req)
+
+                    # The requirement files can have the same name but in different directories:
+                    # requirements=["test/requirements.txt", "a/b/c/requirements.txt"]
+                    # To uniquely identify these files, we add a `idx` prefix to every file's basename
+                    # - `test/requirements.txt` -> `/.0_requirements.txt` in context -> `/.uv/0/requirements.txt` to uv
+                    # - `a/b/c/requirements.txt` -> `/.1_requirements.txt` in context -> `/.uv/1/requirements.txt` to uv
+                    return {
+                        "local_path": local_path,
+                        "context_path": f"/.{idx}_{basename}",
+                        "dest_path": f"{UV_ROOT}/{idx}/{basename}",
+                    }
+
+                requirement_paths = [_generate_paths(idx, req) for idx, req in enumerate(requirements)]
+                requirements_cli = " ".join(f"--requirements {req['dest_path']}" for req in requirement_paths)
+                uv_pip_args.append(requirements_cli)
+
+                commands.extend([f"COPY {req['context_path']} {req['dest_path']}" for req in requirement_paths])
+                context_files.update({req["context_path"]: req["local_path"] for req in requirement_paths})
+
+            uv_pip_args.extend(shlex.quote(p) for p in sorted(pkgs))
+            uv_pip_args_joined = " ".join(uv_pip_args)
+
+            commands.append(f"RUN {UV_ROOT}/uv pip install {uv_pip_args_joined}")
+
+            return DockerfileSpec(commands=commands, context_files=context_files)
+
+        return _Image._from_args(
+            base_images={"base": self},
+            dockerfile_function=build_dockerfile,
+            force_build=self.force_build or force_build,
+            gpu_config=parse_gpu_config(gpu),
+            secrets=secrets,
+        )
+
     def poetry_install_from_file(
         self,
         poetry_pyproject_toml: str,
         poetry_lockfile: Optional[str] = None,  # Path to lockfile. If not provided, uses poetry.lock in same directory.
         *,
         ignore_lockfile: bool = False,  # If set to True, do not use poetry.lock, even when present
-        # If set to True, use old installer. See https://github.com/python-poetry/poetry/issues/3336
-        old_installer: bool = False,
         force_build: bool = False,  # Ignore cached builds, similar to 'docker build --no-cache'
         # Selected optional dependency groups to install (See https://python-poetry.org/docs/cli/#install)
         with_: list[str] = [],
         # Selected optional dependency groups to exclude (See https://python-poetry.org/docs/cli/#install)
         without: list[str] = [],
         only: list[str] = [],  # Only install dependency groups specifed in this list.
-        secrets: Sequence[_Secret] = [],
+        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,
+        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.
@@ -1245,12 +1367,26 @@ class _Image(_Object, type_prefix="im"):
 
         Note that the root project of the poetry project is not installed, only the dependencies.
         For including local python source files see `add_local_python_source`
+
+        Poetry will be installed to the Image (using pip) unless `poetry_version` is set to None.
+        Note that the interpretation of `poetry_version="latest"` depends on the Modal Image Builder
+        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)}
 
-            commands = ["FROM base", "RUN python -m pip install poetry~=1.7"]
+            commands = ["FROM base"]
+            if poetry_version is not None:
+                if poetry_version == "latest":
+                    poetry_spec = "~=1.7" if version <= "2024.10" else ""
+                else:
+                    poetry_spec = f"=={poetry_version}"  # TODO: support other versions
+                commands += [f"RUN python -m pip install poetry{poetry_spec}"]
 
             if old_installer:
                 commands += ["RUN poetry config experimental.new-installer false"]
@@ -1281,7 +1417,8 @@ class _Image(_Object, type_prefix="im"):
 
             if only:
                 install_cmd += f" --only {','.join(only)}"
-            install_cmd += " --compile"  # no .pyc compilation slows down cold-start.
+
+            install_cmd += " --compile"  # Always compile .pyc during build; avoid recompiling on every cold start
 
             commands += [
                 "COPY /.pyproject.toml /tmp/poetry/pyproject.toml",
@@ -1299,13 +1436,181 @@ class _Image(_Object, type_prefix="im"):
             gpu_config=parse_gpu_config(gpu),
         )
 
+    def uv_sync(
+        self,
+        uv_project_dir: str = "./",  # Path to local uv managed project
+        *,
+        force_build: bool = False,  # Ignore cached builds, similar to 'docker build --no-cache'
+        groups: Optional[list[str]] = None,  # Dependency group to install using `uv sync --group`
+        extras: Optional[list[str]] = None,  # Optional dependencies to install using `uv sync --extra`
+        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
+        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`.
+
+        **Examples**
+        ```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 []
+            elif isinstance(items, list):
+                return items
+            else:
+                raise InvalidError(f"{name} must be None or a list of strings")
+
+        groups = _normalize_items(groups, "groups")
+        extras = _normalize_items(extras, "extras")
+
+        def _check_pyproject_toml(pyproject_toml: str, version: ImageBuilderVersion):
+            if not os.path.exists(pyproject_toml):
+                raise InvalidError(f"Expected {pyproject_toml} to exist")
+
+            import toml
+
+            with open(pyproject_toml) as f:
+                pyproject_toml_content = toml.load(f)
+
+            if (
+                "tool" in pyproject_toml_content
+                and "uv" in pyproject_toml_content["tool"]
+                and "workspace" in pyproject_toml_content["tool"]["uv"]
+            ):
+                raise InvalidError("uv workspaces are not supported")
+
+            if version > "2024.10":
+                # For builder version > 2024.10, modal is mounted at runtime and is not
+                # a requirement in `uv.lock`
+                return
+
+            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 (
+                    "dependency-groups" in pyproject_toml_content
+                    and group in pyproject_toml_content["dependency-groups"]
+                ):
+                    dependencies += pyproject_toml_content["dependency-groups"][group]
+
+            for extra in extras:
+                if (
+                    "project" in pyproject_toml_content
+                    and "optional-dependencies" in pyproject_toml_content["project"]
+                    and extra in pyproject_toml_content["project"]["optional-dependencies"]
+                ):
+                    dependencies += pyproject_toml_content["project"]["optional-dependencies"][extra]
+
+            PACKAGE_REGEX = re.compile(r"^[\w-]+")
+
+            def _extract_package(package) -> str:
+                m = PACKAGE_REGEX.match(package)
+                return m.group(0) if m else ""
+
+            if not any(_extract_package(dependency) == "modal" for dependency in dependencies):
+                raise InvalidError(
+                    "Image builder version <= 2024.10 requires modal to be specified in your pyproject.toml file"
+                )
+
+        def build_dockerfile(version: ImageBuilderVersion) -> DockerfileSpec:
+            uv_project_dir_ = os.path.expanduser(uv_project_dir)
+            pyproject_toml = os.path.join(uv_project_dir_, "pyproject.toml")
+
+            UV_ROOT = "/.uv"
+            uv_sync_args = [
+                f"--project={UV_ROOT}",
+                "--no-install-workspace",  # Do not install the root project or any "uv workspace"
+                "--compile-bytecode",
+            ]
+
+            for group in groups:
+                uv_sync_args.append(f"--group={group}")
+            for extra in extras:
+                uv_sync_args.append(f"--extra={extra}")
+            if extra_options:
+                uv_sync_args.append(extra_options)
+
+            commands = ["FROM base"]
+
+            if uv_version is None:
+                commands.append(f"COPY --from=ghcr.io/astral-sh/uv:latest /uv {UV_ROOT}/uv")
+            else:
+                commands.append(f"COPY --from=ghcr.io/astral-sh/uv:{uv_version} /uv {UV_ROOT}/uv")
+
+            context_files = {}
+
+            _check_pyproject_toml(pyproject_toml, version)
+
+            context_files["/.pyproject.toml"] = pyproject_toml
+            commands.append(f"COPY /.pyproject.toml {UV_ROOT}/pyproject.toml")
+
+            uv_lock = os.path.join(uv_project_dir_, "uv.lock")
+            if os.path.exists(uv_lock):
+                context_files["/.uv.lock"] = uv_lock
+                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 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
+                    # during build time.
+                    uv_sync_args.append("--frozen")
+
+            uv_sync_args_joined = " ".join(uv_sync_args).strip()
+
+            commands += [
+                f"RUN {UV_ROOT}/uv sync {uv_sync_args_joined}",
+                f"ENV PATH={UV_ROOT}/.venv/bin:$PATH",
+            ]
+
+            return DockerfileSpec(commands=commands, context_files=context_files)
+
+        return _Image._from_args(
+            base_images={"base": self},
+            dockerfile_function=build_dockerfile,
+            force_build=self.force_build or force_build,
+            secrets=secrets,
+            gpu_config=parse_gpu_config(gpu),
+        )
+
     def dockerfile_commands(
         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,
@@ -1351,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)
 
@@ -1370,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,
         )
@@ -1379,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)
@@ -1404,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
@@ -1422,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
@@ -1437,8 +1748,7 @@ class _Image(_Object, type_prefix="im"):
                 python_version = "3.9"  # Backcompat for old hardcoded default param
             validated_python_version = _validate_python_version(python_version, version)
             micromamba_version = _base_image_config("micromamba", version)
-            debian_codename = _base_image_config("debian", version)
-            tag = f"mambaorg/micromamba:{micromamba_version}-{debian_codename}-slim"
+            tag = f"mambaorg/micromamba:{micromamba_version}"
             setup_commands = [
                 'SHELL ["/usr/local/bin/_dockerfile_shell.sh"]',
                 "ENV MAMBA_DOCKERFILE_ACTIVATE=1",
@@ -1468,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
@@ -1623,7 +1939,7 @@ class _Image(_Object, type_prefix="im"):
         """Build a Modal image from a private image in Google Cloud Platform (GCP) Artifact Registry.
 
         You will need to pass a `modal.Secret` containing [your GCP service account key data](https://cloud.google.com/iam/docs/keys-create-delete#creating)
-        as `SERVICE_ACCOUNT_JSON`. This can be done from the [Secrets](/secrets) page.
+        as `SERVICE_ACCOUNT_JSON`. This can be done from the [Secrets](https://modal.com/secrets) page.
         Your service account should be granted a specific role depending on the GCP registry used:
 
         - For Artifact Registry images (`pkg.dev` domains) use
@@ -1673,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**
@@ -1710,12 +2032,13 @@ 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] = {},
         ignore: Union[Sequence[str], Callable[[Path], bool]] = AUTO_DOCKERIGNORE,
     ) -> "_Image":
         """Build a Modal image from a local Dockerfile.
@@ -1767,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
 
@@ -1785,10 +2106,11 @@ 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,
+            build_args=build_args,
         )
 
         # --- Now add in the modal dependencies, and, optionally a Python distribution
@@ -1880,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`.
@@ -1905,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,
@@ -1917,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**
 
@@ -1958,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):
@@ -1987,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(
@@ -2053,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**
 
@@ -2123,5 +2465,15 @@ class _Image(_Object, type_prefix="im"):
                 if task_log.data:
                     yield task_log.data
 
+    async def hydrate(self, client: Optional[_Client] = None) -> Self:
+        """mdmd:hidden"""
+        # Image inherits hydrate() from Object but can't be hydrated on demand
+        # Overriding the method lets us hide it from the docs and raise a better error message
+        if not self.is_hydrated:
+            raise ExecutionError(
+                "Images cannot currently be hydrated on demand; you can build an Image by running an App that uses it."
+            )
+        return self
+
 
 Image = synchronize_api(_Image)