Skip to main content
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.

​
Factory methods

​
Image.debian_slim

modal.Image.debian_slim(
    python_version: Optional[str] = None,
)
Default image, based on the official Debian slim image.
​
python_version
str
Python version to use (e.g., “3.11”, “3.12”). Defaults to the version you’re currently running locally.
Example: 
image = modal.Image.debian_slim(python_version="3.11")

​
Image.from_registry

modal.Image.from_registry(
    tag: str,
    *,
    secret: Optional[Secret] = None,
    add_python: Optional[str] = None,
    **kwargs,
)
Create an image from a public or private registry.
​
tag
str
required
Full image tag (e.g., “ubuntu:22.04” or “nvidia/cuda:12.2.0-devel-ubuntu22.04”).
​
secret
Secret
Optional secret for pulling from private registries.
​
add_python
str
Optionally install a Python version onto the image (e.g., “3.11”).
Example: 
image = modal.Image.from_registry(
    "nvidia/cuda:12.2.0-devel-ubuntu22.04",
    add_python="3.11"
)

​
Image.micromamba

modal.Image.micromamba(
    python_version: Optional[str] = None,
)
Create an image using micromamba for fast package installation.
​
python_version
str
Python version to use. Defaults to your current version.
Example: 
image = modal.Image.micromamba(python_version="3.11")

​
Image.from_dockerfile

modal.Image.from_dockerfile(
    path: Union[str, Path],
    *,
    context_dir: Optional[Union[str, Path]] = None,
    ignore: Union[Sequence[str], Callable[[Path], bool]] = [],
)
Create an image from a Dockerfile.
​
path
Union[str, Path]
required
Path to the Dockerfile.
​
context_dir
Union[str, Path]
Directory to use as build context. Defaults to the directory containing the Dockerfile.
​
ignore
Union[Sequence[str], Callable]
Files to ignore in the context (dockerignore syntax or callable).
Example: 
image = modal.Image.from_dockerfile("./Dockerfile")

​
Image modification methods

​
image.pip_install

image.pip_install(
    *packages: Union[str, list[str]],
    find_links: Optional[str] = None,
    index_url: Optional[str] = None,
    extra_index_url: Optional[str] = None,
    pre: bool = False,
    extra_options: str = "",
    force_build: bool = False,
    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.
​
packages
str
List of packages to install (e.g., “numpy”, “pandas>=1.0”).
​
find_links
str
Passes -f (—find-links) to pip install.
​
index_url
str
Passes -i (—index-url) to pip install.
​
extra_index_url
str
Passes —extra-index-url to pip install.
​
pre
bool
default:"False"
Allow pre-releases.
​
extra_options
str
Additional options to pass to pip install (e.g., “—no-build-isolation”).
​
force_build
bool
default:"False"
Ignore cached builds.
​
env
dict[str, str]
Environment variables to set during build.
​
secrets
Collection[Secret]
Secrets to inject during build.
​
gpu
GPU_T
GPU to use during build.
Example: 
image = (
    modal.Image.debian_slim()
    .pip_install("numpy", "pandas>=1.0")
)

​
image.pip_install_from_requirements

image.pip_install_from_requirements(
    requirements_txt: str,
    *,
    find_links: Optional[str] = None,
    index_url: Optional[str] = None,
    extra_index_url: Optional[str] = None,
    pre: bool = False,
    extra_options: str = "",
    force_build: bool = False,
    env: Optional[dict[str, Optional[str]]] = None,
    secrets: Optional[Collection[Secret]] = None,
    gpu: GPU_T = None,
) -> Image
Install Python packages from a local requirements.txt file.
​
requirements_txt
str
required
Path to requirements.txt file.
Example: 
image = (
    modal.Image.debian_slim()
    .pip_install_from_requirements("requirements.txt")
)

​
image.run_commands

image.run_commands(
    *commands: Union[str, list[str]],
    force_build: bool = False,
    secrets: Collection[Secret] = [],
    gpu: GPU_T = None,
) -> Image
Run shell commands during image build.
​
commands
str
Shell commands to run.
​
force_build
bool
default:"False"
Ignore cached builds.
​
secrets
Collection[Secret]
Secrets to inject during build.
​
gpu
GPU_T
GPU to use during build.
Example: 
image = (
    modal.Image.debian_slim()
    .run_commands(
        "apt-get update",
        "apt-get install -y git"
    )
)

​
image.add_local_file

image.add_local_file(
    local_path: Union[str, Path],
    remote_path: str,
    *,
    copy: bool = False,
) -> Image
Adds a local file to the image at remote_path within the container.
​
local_path
Union[str, Path]
required
Local path to the file.
​
remote_path
str
required
Absolute path in the container where file will be placed.
​
copy
bool
default:"False"
If True, copy into image layer at build time. If False, add on container startup.
Example: 
image = (
    modal.Image.debian_slim()
    .add_local_file("./config.json", "/app/config.json")
)

​
image.add_local_dir

image.add_local_dir(
    local_path: Union[str, Path],
    remote_path: str,
    *,
    copy: bool = False,
    ignore: Union[Sequence[str], Callable[[Path], bool]] = [],
) -> Image
Adds a local directory’s contents to the image at remote_path.
​
local_path
Union[str, Path]
required
Local path to the directory.
​
remote_path
str
required
Absolute path in the container.
​
copy
bool
default:"False"
If True, copy into image layer. If False, add on startup.
​
ignore
Union[Sequence[str], Callable]
Files to exclude (dockerignore syntax or callable).
Example: 
image = (
    modal.Image.debian_slim()
    .add_local_dir("./src", "/app/src", ignore=["*.pyc", "__pycache__"])
)

​
image.add_local_python_source

image.add_local_python_source(
    *modules: str,
    copy: bool = False,
    ignore: Union[Sequence[str], Callable[[Path], bool]] = NON_PYTHON_FILES,
) -> Image
Adds locally available Python packages/modules to containers.
​
modules
str
required
Names of Python packages or modules to include.
​
copy
bool
default:"False"
If True, copy into image layer. If False, add on startup.
​
ignore
Union[Sequence[str], Callable]
Files to exclude. Defaults to non-Python files.
Example: 
image = (
    modal.Image.debian_slim()
    .add_local_python_source("mypackage", "mymodule")
)

​
image.env

image.env(
    env_dict: dict[str, str],
) -> Image
Set environment variables in the image.
​
env_dict
dict[str, str]
required
Dictionary of environment variable name-value pairs.
Example: 
image = (
    modal.Image.debian_slim()
    .env({"MY_VAR": "value", "DEBUG": "true"})
)

​
image.workdir

image.workdir(
    path: str,
) -> Image
Set the working directory for subsequent commands and when the container starts.
​
path
str
required
Absolute path to use as working directory.
Example: 
image = (
    modal.Image.debian_slim()
    .workdir("/app")
)

Build docs developers (and LLMs) love

Get started for freeTalk to us