Modal Container Images

Use this skill when defining the environment (packages, system deps, files, GPU libraries) that Modal Functions run in.

When to Use This Skill

• Installing Python packages for remote Functions
• Adding system packages (apt)
• Bringing local files/code into containers
• Using existing Dockerfiles or registry images
• Setting up CUDA/GPU-accelerated environments
• Publishing/sharing canonical images across Apps and Sandboxes (Named Images)
• Composing reusable Image recipes with pipe()
• Optimizing image build times and layer caching

Core Workflow

1. Start from a base image (usually modal.Image.debian_slim())
2. Chain methods to add packages, files, and commands
3. Assign to Functions via @app.function(image=my_image) or set as App default

image = (
    modal.Image.debian_slim(python_version="3.13")
    .apt_install("git")
    .uv_pip_install("torch<3")
    .env({"MY_VAR": "value"})
    .run_commands("echo 'ready'")
)

@app.function(image=image)
def f():
    import torch

Python 3.14 is supported; 3.9 is dropped (EOL). Prefer python_version="3.12"+ for new images.

Named Images (Recommended for Shared Images)

Publish a built Image under a name (Modal-native registry). Prefer Named Images when sharing a canonical Image across many Apps or Sandboxes — lookups never rebuild.

app = modal.App.lookup("image-builds", create_if_missing=True)

image = (
    modal.Image.debian_slim(python_version="3.12")
    .apt_install("git")
    .uv_pip_install("numpy", "pandas")
)

with modal.enable_output():
    image.build(app).publish("analytics-runtime")       # :latest
    image.publish("analytics-runtime:v1")               # explicit tag

# Lookup — succeeds or raises NotFoundError; never triggers a build
runtime = modal.Image.from_name("analytics-runtime")
runtime_v1 = modal.Image.from_name("analytics-runtime:v1")

sb = modal.Sandbox.create(image=runtime, app=app)

@app.function(image=modal.Image.from_name("analytics-runtime"))
def train():
    import pandas as pd

modal image names   # list current name → Image assignments

Redeploy Apps that reference a name after publishing a new version — deployed Functions do not auto-pick up new publishes.

Image Methods (Build Order Matters)

Python packages

image.uv_pip_install("pandas==2.2.0", "numpy")   # fast, uses uv
image.pip_install("pandas==2.2.0", "numpy")       # fallback, uses pip
image.uv_pip_install_from_requirements("requirements.txt")
image.uv_pip_install_from_pyproject("pyproject.toml")

Pin versions tightly for reproducibility: "torch==2.8.0" over "torch<3".

System packages

image.apt_install("ffmpeg", "libsndfile1")

Local files and code

image.add_local_dir("./config", remote_path="/root/config")
image.add_local_file("model.bin", remote_path="/root/model.bin")
image.add_local_python_source("my_module")  # by module name

By default, local files are added at container startup (fast redeploy). Use copy=True to bake into the image layer.

Environment variables

image.env({"TRANSFORMERS_CACHE": "/vol/cache"})

Run arbitrary commands

image.run_commands("git clone https://github.com/org/repo")

Run a Python function during build

def download_model():
    from huggingface_hub import snapshot_download
    snapshot_download("meta-llama/Llama-3-8B")

image = modal.Image.debian_slim().pip_install("huggingface_hub").run_function(download_model)

Reusable recipes with pipe()

def workspace_setup(image: modal.Image, repo: str) -> modal.Image:
    return image.run_commands(f"git clone {repo}").uv_pip_install(".")

image = (
    modal.Image.debian_slim()
    .apt_install("git")
    .pipe(workspace_setup, "https://github.com/example/repo.git")
)

Empty images with from_scratch()

# No OS/shell/Python — for lightweight Sandbox mounts via mount_image
empty = modal.Image.from_scratch().add_local_file("./tool", "/bin/tool", copy=True)

Cannot chain pip_install / run Functions on scratch images.

Alternative Base Images

modal.Image.from_registry("nvidia/cuda:12.4.0-devel-ubuntu22.04")
modal.Image.from_dockerfile("./Dockerfile")
modal.Image.from_dockerfile("./Dockerfile", build_args={"VERSION": "1.2"})
modal.Image.from_gcp_artifact_registry("us-docker.pkg.dev/project/repo/image:tag")
modal.Image.from_aws_ecr("123456789.dkr.ecr.us-east-1.amazonaws.com/my-image:tag")

from_dockerfile supports COPY --chmod / COPY --chown. Pass build_args= on both from_dockerfile() and dockerfile_commands().

Private registries with secrets

modal.Image.from_registry(
    "my-registry.example.com/my-image:latest",
    secret=modal.Secret.from_name("registry-creds"),  # REGISTRY_USERNAME, REGISTRY_PASSWORD
)

eStargz Fast Pull

Modal pulls only the layers needed for cold start using eStargz lazy loading. This happens automatically for images built with Modal. For from_registry images, Modal converts to eStargz on first pull — subsequent pulls are fast.

Use force_build=True on any image method to skip cache and rebuild. Use image.build(app) to eagerly build (especially useful before Sandbox create).

Go SDK

mc, _ := modal.NewClient()

// From registry
image := mc.Images.FromRegistry("python:3.11-slim", nil)

// With Dockerfile commands
image = image.DockerfileCommands([]string{
    "RUN apt-get update && apt-get install -y git",
    "RUN pip install numpy pandas",
}, nil)

// GPU build layer
image = image.DockerfileCommands([]string{
    "RUN pip install torch",
}, &modal.ImageDockerfileCommandsParams{
    GPU: "T4",
})

// Private registry
secret, _ := mc.Secrets.FromName(ctx, "docker-hub-secret", nil)
privateImage := mc.Images.FromRegistry("myorg/private:latest", &modal.ImageFromRegistryParams{
    Secret: secret,
})

// AWS ECR / GCP AR
awsSecret, _ := mc.Secrets.FromName(ctx, "aws-secret", nil)
ecrImage := mc.Images.FromAwsEcr("123456789.dkr.ecr.us-east-1.amazonaws.com/img:latest", awsSecret)

// Build eagerly + publish named Image
app, _ := mc.Apps.FromName(ctx, "my-app", &modal.AppFromNameParams{CreateIfMissing: true})
built, _ := image.Build(ctx, app)
_ = built.Publish(ctx, "analytics-runtime", nil)

TypeScript SDK

import { ModalClient } from "modal";
const modal = new ModalClient();

// From registry
const image = modal.images.fromRegistry("python:3.13-slim");

// Chain Dockerfile commands
const customImage = image
    .dockerfileCommands(["RUN apt-get update && apt-get install -y git"])
    .dockerfileCommands(["RUN pip install torch"], { gpu: "A100" });

// Private registry
const secret = await modal.secrets.fromName("docker-hub-secret");
const privateImage = modal.images.fromRegistry("myorg/private:latest", secret);

// AWS ECR / GCP AR
const awsSecret = await modal.secrets.fromName("aws-credentials");
const ecrImage = modal.images.fromAwsEcr("123456789.dkr.ecr.us-east-1.amazonaws.com/img:latest", awsSecret);

// Build eagerly + publish named Image
const app = await modal.apps.fromName("my-app", { createIfMissing: true });
const built = await customImage.build(app);
await built.publish("analytics-runtime");

Symptom Triage

"Module not found" in container

• Add the package via uv_pip_install or pip_install
• For local code, use add_local_python_source("module_name")
• Import inside the function body, not at module top level

Slow image builds

• Order methods so slow/stable layers come first (apt_install before pip_install)
• Pin versions to maximize layer cache hits
• Use uv_pip_install over pip_install for faster installs
• Use add_local_dir without copy=True for frequently changing files

GPU library issues

• See references/gpu-images-cuda.md for CUDA stack details
• Use from_registry with NVIDIA base images for bleeding-edge CUDA
• torch bundles CUDA deps — just pip_install("torch")

Named Image NotFoundError

• Confirm the name was published: modal image names
• Tag defaults to :latest if omitted
• Lookup never builds — publish first in a separate script

Reference Map

• references/image-basics.md — method chaining, layer caching, base images, pipe(), from_scratch()
• references/gpu-images-cuda.md — CUDA stack, torch, flash-attn setup
• references/dockerfiles-registries.md — Dockerfile, build_args, --chmod/--chown, ECR, GCP AR
• references/local-files-mounts.md — add_local_dir, add_local_file, add_local_python_source

Guardrails

• Import heavy libraries inside function bodies, not at module top level
• Pin dependency versions for reproducible builds
• Prefer uv_pip_install over pip_install for speed
• Prefer Named Images (publish / from_name) for canonical images shared across Apps/Sandboxes
• Each Function can have its own image — no need for virtual environments
• Images are cached and reused across deployments when unchanged
• Python 3.14 supported; 3.9 no longer supported

Key References

• https://modal.com/docs/guide/images
• https://modal.com/docs/guide/named-images
• https://modal.com/docs/sdk/py/latest/Image
• https://modal.com/docs/sdk/py/changelog (1.5.x)