Skip to main content
Images define the container environment for your Modal Sandboxes and Functions. The Images API provides methods to reference existing container images or build custom images.

​
Access the Images API

import { ModalClient } from "modal";

const modal = new ModalClient();
const image = modal.images.fromRegistry("python:3.13");

​
Methods

Create an Image from a container registry tag.
​
tag
string
required
The registry tag for the image (e.g., "python:3.13", "nginx:alpine").
​
secret
Secret
Optional Secret containing credentials for private registry authentication.
​
return
Image
An Image object that can be built or used directly.
// Public image
const image = modal.images.fromRegistry("alpine:3.21");

// Private registry with authentication
const secret = await modal.secrets.fromName("docker-hub-secret");
const image = modal.images.fromRegistry("myorg/private-image:latest", secret);
Create an Image from AWS Elastic Container Registry (ECR).
​
tag
string
required
The ECR image tag.
​
secret
Secret
required
Secret containing AWS credentials for ECR authentication.
​
return
Image
An Image object.
const awsSecret = await modal.secrets.fromName("aws-credentials");
const image = modal.images.fromAwsEcr(
  "123456789.dkr.ecr.us-east-1.amazonaws.com/my-image:latest",
  awsSecret
);
Create an Image from Google Cloud Platform Artifact Registry.
​
tag
string
required
The GCP Artifact Registry image tag.
​
secret
Secret
required
Secret containing GCP credentials for authentication.
​
return
Image
An Image object.
const gcpSecret = await modal.secrets.fromName("gcp-credentials");
const image = modal.images.fromGcpArtifactRegistry(
  "us-docker.pkg.dev/my-project/my-repo/my-image:latest",
  gcpSecret
);
Create an Image from an existing Image ID.
​
imageId
string
required
The Modal Image ID.
​
return
Promise<Image>
The referenced Image object.
const image = await modal.images.fromId("im-123456");
Delete an Image by ID. This operation is irreversible.
​
imageId
string
required
The ID of the Image to delete.
​
params
ImageDeleteParams
Optional parameters (currently empty).
await modal.images.delete("im-123456");
Deletion is irreversible and will prevent Functions/Sandboxes from using the Image. Only the image with the specified ID is deleted, not intermediate layers.

​
Image object

The Image object represents a container image that can be built or used with Sandboxes.

​
Properties

​
imageId
string
Unique identifier for the Image. Empty string if not yet built.

​
Methods

​
dockerfileCommands(commands, params?)

Extend an image with arbitrary Dockerfile-like commands. Each call creates a new Image layer.
​
commands
string[]
required
Array of Dockerfile commands (e.g., ["RUN pip install numpy", "ENV LANG=en_US.UTF-8"]).
​
params
ImageDockerfileCommandsParams
Build configuration for this layer
​
return
Image
A new Image object with the additional layer.
const image = modal.images
  .fromRegistry("python:3.13-slim")
  .dockerfileCommands([
    "RUN apt-get update && apt-get install -y git",
    "RUN pip install numpy pandas",
  ])
  .dockerfileCommands(
    ["RUN pip install torch torchvision"],
    { gpu: "A100" } // Use GPU for this layer
  );
COPY commands that copy from local context are not yet supported. Only COPY --from= is allowed.

​
build(app)

Eagerly build the Image on Modal.
​
app
App
required
The App context to use for building.
​
return
Promise<Image>
The built Image with an assigned imageId.
const app = await modal.apps.fromName("my-app", { createIfMissing: true });

const image = modal.images
  .fromRegistry("python:3.13")
  .dockerfileCommands(["RUN pip install fastapi uvicorn"]);

// Build the image
const builtImage = await image.build(app);
console.log(`Image built with ID: ${builtImage.imageId}`);

​
Example: Build a custom Python image

import { ModalClient } from "modal";

const modal = new ModalClient();

const app = await modal.apps.fromName("ml-app", {
  createIfMissing: true,
});

// Build a custom image with ML dependencies
const image = modal.images
  .fromRegistry("python:3.13-slim")
  .dockerfileCommands([
    "RUN apt-get update",
    "RUN apt-get install -y build-essential",
  ])
  .dockerfileCommands([
    "RUN pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118",
  ], {
    gpu: "A100", // Build with GPU for CUDA compatibility
  })
  .dockerfileCommands([
    "RUN pip install transformers datasets",
    "ENV TRANSFORMERS_CACHE=/cache",
  ]);

// Build and use the image
const builtImage = await image.build(app);

const sandbox = await modal.sandboxes.create(app, builtImage, {
  gpu: "A100",
  command: ["python", "train.py"],
});

​
Example: Use a private registry

import { ModalClient } from "modal";

const modal = new ModalClient();

// Create a secret for Docker Hub authentication
const dockerSecret = await modal.secrets.fromObject({
  DOCKER_USERNAME: "myusername",
  DOCKER_PASSWORD: "mypassword",
});

// Use a private image
const image = modal.images.fromRegistry(
  "myorg/private-image:v1.0",
  dockerSecret
);

const app = await modal.apps.fromName("my-app", { createIfMissing: true });
const sandbox = await modal.sandboxes.create(app, image);

Build docs developers (and LLMs) love

Get started for freeTalk to us