Modal Images Reference

This document provides detailed reference for building container images in Modal.

Base Images

debian_slim

Minimal Debian-based image, recommended for most use cases.

image = modal.Image.debian_slim(python_version="3.12")

micromamba

For conda/mamba package management.

image = modal.Image.micromamba().micromamba_install(
    "pytorch", "cudatoolkit=11.8",
    channels=["pytorch", "conda-forge"]
)

from_registry

Use any public Docker image.

image = modal.Image.from_registry("pytorch/pytorch:2.0.0-cuda11.7-cudnn8-runtime")

# Add Python to images without it
image = modal.Image.from_registry("ubuntu:22.04", add_python="3.12")

from_dockerfile

Build from existing Dockerfile.

image = modal.Image.from_dockerfile("./Dockerfile")

from_aws_ecr

Pull from private AWS ECR.

aws_secret = modal.Secret.from_name("my-aws-secret")
image = modal.Image.from_aws_ecr(
    "123456789.dkr.ecr.us-east-1.amazonaws.com/my-repo:latest",
    secret=aws_secret,
)

Image Methods

Package Installation

image = (
    modal.Image.debian_slim()
    # Python packages
    .pip_install("torch", "transformers")           # Standard pip
    .uv_pip_install("numpy", "pandas")              # Fast uv installer
    .pip_install("flash-attn", gpu="H100")          # With GPU access
    
    # System packages
    .apt_install("git", "ffmpeg", "curl")
    
    # Conda packages
    # (only with micromamba base)
    .micromamba_install("pytorch", channels=["pytorch"])
)

Adding Local Files

image = (
    modal.Image.debian_slim()
    # Add local directory
    .add_local_dir("./config", remote_path="/app/config")
    
    # Add single file
    .add_local_file("./model.py", remote_path="/app/model.py")
    
    # Add Python module (for imports)
    .add_local_python_source("my_module")
)

Environment Configuration

image = (
    modal.Image.debian_slim()
    # Environment variables
    .env({"MY_VAR": "value", "DEBUG": "true"})
    
    # Working directory
    .workdir("/app")
    
    # Custom entrypoint
    .entrypoint(["/usr/bin/my_entrypoint.sh"])
)

Running Commands

image = (
    modal.Image.debian_slim()
    # Shell commands
    .run_commands(
        "git clone https://github.com/user/repo",
        "cd repo && pip install -e ."
    )
    
    # Python function during build
    .run_function(download_models, secrets=[hf_secret])
)

Build Optimization

Layer Ordering

Order layers from least to most frequently changed:

image = (
    modal.Image.debian_slim()
    .apt_install("ffmpeg")              # 1. System packages (rarely change)
    .pip_install("torch==2.1.0")        # 2. Large dependencies (pinned)
    .pip_install("transformers")        # 3. Application dependencies
    .add_local_python_source("app")     # 4. Application code (changes often)
)

Force Rebuild

# Force specific layer to rebuild
image = (
    modal.Image.debian_slim()
    .pip_install("my-package", force_build=True)
)

# Force all images to rebuild
MODAL_FORCE_BUILD=1 modal run app.py

# Ignore cache without breaking it
MODAL_IGNORE_CACHE=1 modal run app.py

GPU During Build

# Some packages need GPU access during installation
image = (
    modal.Image.debian_slim()
    .pip_install("bitsandbytes", gpu="H100")
)

CUDA Images

For libraries requiring full CUDA toolkit:

cuda_version = "12.8.1"
os_version = "ubuntu24.04"

image = (
    modal.Image.from_registry(
        f"nvidia/cuda:{cuda_version}-devel-{os_version}",
        add_python="3.12"
    )
    .entrypoint([])  # Remove base image entrypoint
    .pip_install("torch", "flash-attn")
)

Image Imports

Handle packages that only exist in the container:

image = modal.Image.debian_slim().pip_install("torch", "transformers")

# Imports only happen when container runs
with image.imports():
    import torch
    from transformers import pipeline

@app.function(image=image)
def my_function():
    # torch and pipeline are available here
    model = pipeline("text-generation")
    ...