modal.Image

Base class for container images to run functions in.

Do not construct this class directly; instead use one of its static factory methods, such as modal.Image.debian_slim, modal.Image.from_registry, or modal.Image.micromamba.

add_local_file

Adds a local file to the image at remote_path within the container

By default (copy=False), the files are added to containers on startup and are not built into the actual Image, which speeds up deployment.

Set copy=True to copy the files into an Image layer at build time instead, similar to how COPY works in a Dockerfile.

copy=True can slow down iteration since it requires a rebuild of the Image and any subsequent build steps whenever the included files change, but it is required if you want to run additional build steps after this one.

Added in v0.66.40: This method replaces the deprecated modal.Image.copy_local_file method.

add_local_dir

Adds a local directory’s content to the image at remote_path within the container

By default (copy=False), the files are added to containers on startup and are not built into the actual Image, which speeds up deployment.

Set copy=True to copy the files into an Image layer at build time instead, similar to how COPY works in a Dockerfile.

Usage:

Added in v0.66.40: This method replaces the deprecated modal.Image.copy_local_dir method.

add_local_python_source

Adds locally available Python packages/modules to containers

Adds all files from the specified Python package or module to containers running the Image.

Packages are added to the /root directory of containers, which is on the PYTHONPATH of any executed Modal Functions, enabling import of the module by that name.

By default (copy=False), the files are added to containers on startup and are not built into the actual Image, which speeds up deployment.

Set copy=True to copy the files into an Image layer at build time instead. This can slow down iteration since it requires a rebuild of the Image and any subsequent build steps whenever the included files change, but it is required if you want to run additional build steps after this one.

Note: This excludes all dot-prefixed subdirectories or files and all .pyc/__pycache__ files. To add full directories with finer control, use .add_local_dir() instead and specify /root as the destination directory.

By default only includes .py-files in the source modules. Set the ignore argument to a list of patterns or a callable to override this behavior, e.g.:

Added in v0.67.28: This method replaces the deprecated modal.Mount.from_local_python_packages pattern.

from_id

Construct an Image from an id and look up the Image result.

The ID of an Image object can be accessed using .object_id.

build

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

Alternatively, you can pre-build a image and use it in a sandbox.

Note

For defining Modal functions, images are built automatically when deploying or running an App. You do not need to built the image explicitly:

pip_install

Install a list of Python packages using pip.

Examples

Simple installation:

More complex installation:

pip_install_private_repos

Install a list of Python packages from private git repositories using pip.

This method currently supports Github and Gitlab only.

Github: Provide a modal.Secret that contains a GITHUB_TOKEN key-value pair
Gitlab: Provide a modal.Secret that contains a GITLAB_TOKEN key-value pair

These API tokens should have permissions to read the list of private repositories provided as arguments.

We recommend using Github’s ‘fine-grained’ access tokens. These tokens are repo-scoped, and avoid granting read permission across all of a user’s private repos.

Example

pip_install_from_requirements

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

pip_install_from_pyproject

Install dependencies specified by a local pyproject.toml file.

optional_dependencies is a list of the keys of the optional-dependencies section(s) of the pyproject.toml file (e.g. test, doc, experiment, etc). When provided, all of the packages in each listed section are installed as well.

uv_pip_install

Install a list of Python packages using uv pip install.

Examples

Simple installation:

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.

poetry_install_from_file

Install poetry dependencies specified by a local pyproject.toml file.

If not provided as argument the path to the lockfile is inferred. However, the file has to exist, unless ignore_lockfile is set to True.

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.

uv_sync

Creates a virtual environment with the dependencies in a uv managed project with uv sync.

Examples

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.

dockerfile_commands

Extend an image with arbitrary Dockerfile-like commands.

Usage:

entrypoint

Set the ENTRYPOINT for the image.

shell

Overwrite default shell for the image.

run_commands

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

micromamba

A Micromamba base image. Micromamba allows for fast building of small Conda-based containers.

micromamba_install

Install a list of additional packages using micromamba.

from_registry

Build a Modal Image from a public or private image registry, such as Docker Hub.

The image must be built for the linux/amd64 platform.

If your image does not come with Python installed, you can use the add_python parameter to specify a version of Python to add to the image. Otherwise, the image is expected to have Python on PATH as python, along with pip.

You may also use setup_dockerfile_commands to run Dockerfile commands before the remaining commands run. This might be useful if you want a custom Python installation or to set a SHELL. Prefer run_commands() when possible though.

To authenticate against a private registry with static credentials, you must set the secret parameter to a modal.Secret containing a username (REGISTRY_USERNAME) and an access token or password (REGISTRY_PASSWORD).

To authenticate against private registries with credentials from a cloud provider, use Image.from_gcp_artifact_registry() or Image.from_aws_ecr().

Examples

from_gcp_artifact_registry

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 as SERVICE_ACCOUNT_JSON. This can be done from the 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 the “Artifact Registry Reader” role
For Container Registry images (gcr.io domains) use the “Storage Object Viewer” role

Note: This method does not use GOOGLE_APPLICATION_CREDENTIALS as that variable accepts a path to a JSON file, not the actual JSON string.

See Image.from_registry() for information about the other parameters.

Example

from_aws_ecr

Build a Modal image from a private image in AWS Elastic Container Registry (ECR).

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

For more details on using an AWS role to access ECR, see the OIDC integration guide.

See Image.from_registry() for information about the other parameters.

Example

from_dockerfile

Build a Modal image from a local Dockerfile.

If your Dockerfile does not have Python installed, you can use the add_python parameter to specify a version of Python to add to the image.

Usage:

debian_slim

Default image, based on the official python Docker images.

apt_install

Install a list of Debian packages using apt.

Example

run_function

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

Only the source code of raw_f, the contents of **kwargs, and any referenced global variables 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

env

Sets the environment variables in an Image.

Example

workdir

Set the working directory for subsequent image build steps and function execution.

Example

cmd

Set the default command (CMD) to run when a container is started.

Used with modal.Sandbox. Has no effect on modal.Function.

Example

imports

Used to import packages in global scope that are only available when running remotely. By using this context manager you can avoid an ImportError due to not having certain packages installed locally.

Usage: