# Images

> Modal Images Reference

- Skill: `samarth777/images` (Agent Skill)
- Install (CLI): `npx skillmds@latest add samarth777/images`
- Raw SKILL.md: https://api.skillmd.com/api/skills/samarth777/images/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: samarth777 (https://skillmd.com/u/samarth777)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/samarth777/images

---

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

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

### `micromamba`
For conda/mamba package management.

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

### `from_registry`
Use any public Docker image.

```python
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.

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

### `from_aws_ecr`
Pull from private AWS ECR.

```python
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

```python
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

```python
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

```python
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

```python
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:

```python
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

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

```bash
# 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

```python
# 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:

```python
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:

```python
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")
    ...
```