modal.Image

class Image(modal.object.Provider)

Base class for container images to run functions in.

Do not construct this class directly; instead use one of its static factory methods, like modal.Image.from_dockerhub or modal.Image.conda.

def __init__(
    self,
    base_images={},
    context_files={},
    dockerfile_commands: Union[list[str], Callable[[], list[str]]] = [],
    secrets=[],
    version=None,
    ref=None,
    gpu=False,
    build_function=None,
):

extend

def extend(self, **kwargs) -> "_Image":

Extend an image (named “base”) with additional options or commands.

This is a low-level command. Generally, you should prefer using functions like Image.pip_install or Image.apt_install if possible.

Example

image = modal.Image.debian_slim().extend(
    dockerfile_commands=[
        "FROM base",
        "WORKDIR /pkg",
        'RUN echo "hello world" > hello.txt',
    ],
    secrets=[secret1, secret2],
)

pip_install

def pip_install(
    self,
    packages: list[str],  # A list of Python packages, eg. ["numpy", "matplotlib>=3.5.0"]
    find_links: Optional[str] = None,
) -> "_Image":

Install a list of Python packages using pip.

pip_install_from_requirements

def pip_install_from_requirements(
    self,
    requirements_txt: str,  # Path to a requirements.txt file.
    find_links: Optional[str] = None,
) -> "_Image":

Install a list of Python packages from a requirements.txt file.

poetry_install_from_file

def poetry_install_from_file(
    self,
    poetry_pyproject_toml: str,
):

Install poetry dependencies specified by a pyproject.toml file.

If a poetry.lock file exists in the same directory, then this will be used to specify exact dependency versions instead.

dockerfile_commands

def dockerfile_commands(
    self,
    dockerfile_commands: Union[str, list[str]],
    context_files: dict[str, str] = {},
    secrets: Collection[_Secret] = [],
    gpu: bool = False,
):

Extend an image with arbitrary Dockerfile-like commands.

run_commands

def run_commands(
    self,
    commands: list[str],
    secrets: Collection[_Secret] = [],
    gpu: bool = False,
):

Extend an image with a list of shell commands to run.

conda

@staticmethod
def conda(python_version: str = "3.9") -> "_Image":

A Conda base image, using miniconda3 and derived from the official Docker Hub image.

conda_install

def conda_install(
    self,
    packages: list[str],  # A list of Python packages, eg. ["numpy", "matplotlib>=3.5.0"]
    *,
    channels: list[str] = [],  # A list of Conda channels, eg. ["conda-forge", "nvidia"]
) -> "_Image":

Install a list of additional packages using conda.

conda_update_from_environment

def conda_update_from_environment(
    self,
    environment_yml: str,
) -> "_Image":

Update conda environment using dependencies from a given environment.yml file.

from_dockerhub

@staticmethod
def from_dockerhub(tag: str, setup_commands: list[str] = [], **kwargs) -> "_Image":

Build a Modal image from a pre-existing image on Docker Hub.

This assumes the following about the image:

  • Python 3.7 or above is present, and is available as python.
  • pip is installed correctly.
  • The image is built for the linux/amd64 platform.

You can use the setup_commands argument to run any commands in the image before Modal is installed. This might be useful if Python or pip is not installed. For instance:

modal.Image.from_dockerhub(
  "gisops/valhalla:latest",
  setup_commands=["apt-get update", "apt-get install -y python3-pip"]
)

from_dockerfile

@staticmethod
def from_dockerfile(path: Union[str, Path]) -> "_Image":

Build a Modal image from a local Dockerfile.

Note that the the following must be true about the image you provide:

  • Python 3.7 or above needs to be present and available as python.
  • pip needs to be installed and available as pip.

debian_slim

@staticmethod
def debian_slim(python_version: Optional[str] = None) -> "_Image":

Default image, based on the official python:X.Y.Z-slim-bullseye Docker images.

apt_install

def apt_install(
    self,
    packages: list[str],  # A list of packages, e.g. ["ssh", "libpq-dev"]
) -> "_Image":

Install a list of Debian packages using apt.

run_function

def run_function(
    self,
    raw_function: Callable[[], Any],
    **kwargs,
) -> "_Image":

Run user-defined function raw_function as an image build step. The function runs just like an ordinary Modal function, and any kwargs accepted by @stub.function (such as Mounts, SharedVolumes, 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.

Note

Only the source code of raw_function and the contents of **kwargs are used to determine whether the image has changed and needs to be rebuilt. If this function references other functions or variables, the image will not be rebuilt if you make changes to them. You can force a rebuild by changing the function’s source code itself.

Example


def my_build_function():
    open("model.pt", "w").write("parameters!")

image = (
    modal.Image
        .debian_slim()
        .pip_install(["torch"])
        .run_function(my_build_function, secrets=[...], mounts=[...])
)