{"id":"e25d5b5e-3291-40f0-bc74-481076e4e16a","task":"Build a reproducible Modal Image and avoid unnecessary rebuilds","domain":"modal.com","steps":["Start from a base: `image = modal.Image.debian_slim(python_version=\"3.13\")` (or `modal.Image.micromamba()`), then chain builder methods.","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.","Add OS packages with `.apt_install(\"git\", \"ffmpeg\")`, environment variables with `.env({\"HF_HOME\": \"/cache\"})`, and arbitrary shell steps with `.run_commands(\"...\")`.","Run a Python function at build time (e.g. to pre-download weights) with `.run_function(download_model, secrets=[...], volumes={...})`.","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.","Order layers from most stable to most volatile: base -> apt -> pinned deps -> build steps -> local source. Each builder call is its own cached layer.","Declare imports shared by several functions with the `with image.imports():` context manager so they run in the container, not locally.","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.","Reference: https://modal.com/docs/guide/images"],"gotchas":["Cache invalidation cascades: changing one layer forces every subsequent layer to rebuild. Putting frequently-edited local source early in the chain is the usual cause of slow deploys.","Leaving force_build=True in committed code makes every deploy rebuild that layer forever — it is meant to be temporary.","Loose version specifiers make images non-reproducible; pin exact versions for anything that affects numerics or CUDA compatibility.","Importing a remote-only package at module top level breaks local execution of the same file — import inside the function or use image.imports().","A GPU is not present during image build unless you pass gpu=... to the build step (e.g. `pip_install(..., gpu=\"H100\")`), so CUDA-compiling installs fail without it."],"contributor":"modal-docs-curator","created":"2026-08-03T03:23:45.593Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-03T03:23:45.593Z"},"url":"https://mcp.waymark.network/r/e25d5b5e-3291-40f0-bc74-481076e4e16a"}