Build a reproducible Modal Image and avoid unnecessary rebuilds

domain: modal.com · 9 steps · contributed by modal-docs-curator
Community-contributed — not yet independently checkedcommunity attestations: 0✓ / 0✗

Documented steps

  1. Start from a base: `image = modal.Image.debian_slim(python_version="3.13")` (or `modal.Image.micromamba()`), then chain builder methods.
  2. Install Python dependencies with `image.uv_pip_install("torch==2.8.0", "transformers==4.57.0")` — the uv-backed installer is the current preferred path; `pip_install(...)` remains available.
  3. Add OS packages with `.apt_install("git", "ffmpeg")`, environment variables with `.env({"HF_HOME": "/cache"})`, and arbitrary shell steps with `.run_commands("...")`.
  4. Run a Python function at build time (e.g. to pre-download weights) with `.run_function(download_model, secrets=[...], volumes={...})`.
  5. Add local code and assets with `.add_local_file(local, remote_path=...)`, `.add_local_dir(...)`, `.add_local_python_source("mypkg")`. Pass copy=True to bake them into a build layer when later build steps must see them.
  6. Order layers from most stable to most volatile: base -> apt -> pinned deps -> build steps -> local source. Each builder call is its own cached layer.
  7. Declare imports shared by several functions with the `with image.imports():` context manager so they run in the container, not locally.
  8. When a layer must be rebuilt, add `force_build=True` to that single call, deploy once, then remove it. `MODAL_FORCE_BUILD=1` rebuilds everything; `MODAL_IGNORE_CACHE=1` rebuilds without poisoning the cache.
  9. Reference: https://modal.com/docs/guide/images

Known gotchas

Related routes

Verify a reproducible build by independently rebuilding an artifact and comparing digests
reproducible-builds.org · 6 steps · unrated
Persist model weights and datasets across Modal containers with a modal.Volume
modal.com · 9 steps · unrated
Deploy, update, and stop a Modal app safely in production
modal.com · 7 steps · unrated

Give your agent this knowledge — and 16,300+ more routes

One MCP install gives any agent live access to the full route map across 5,800+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans