Files
skills/public/modal-image-building.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

561 lines
24 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>modal-image-building</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/modal-image-building.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/modal-image-building">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/modal-image-building.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>modal-image-building</h1><p class="lede">Configuring Modal runtime environments</p><h1>Modal Image Building</h1>
<p><strong>Use this skill when:</strong></p>
<ul><li>Configuring Modal runtime environments</li><li>Installing dependencies for Modal functions</li><li>Optimizing image build times</li><li>Working with custom system packages</li><li>Building reproducible deployments</li></ul>
<h2>Image Basics</h2>
<h3>Base Images</h3>
<p>Choose appropriate base image:</p>
<pre><code class="lang-python">import modal
# Debian Slim (recommended for most cases)
image = modal.Image.debian_slim()
# Debian Slim with specific Python version
image = modal.Image.debian_slim(python_version=&quot;3.11&quot;)
# Ubuntu (when Debian packages unavailable)
image = modal.Image.ubuntu()</code></pre>
<h2>Python Package Installation</h2>
<h3>uv_pip_install (Recommended)</h3>
<p>Use <code>uv_pip_install</code> for fast, reliable installs:</p>
<pre><code class="lang-python"># Single package
image = modal.Image.debian_slim().uv_pip_install(&quot;requests&quot;)
# Multiple packages
image = modal.Image.debian_slim().uv_pip_install(
&quot;numpy&quot;,
&quot;pandas&quot;,
&quot;scikit-learn&quot;
)
# With versions
image = modal.Image.debian_slim().uv_pip_install(
&quot;torch==2.1.0&quot;,
&quot;transformers==4.35.0&quot;,
&quot;accelerate==0.24.0&quot;
)
# From requirements.txt
image = modal.Image.debian_slim().uv_pip_install_from_requirements(
&quot;requirements.txt&quot;
)</code></pre>
<h3>Why uv_pip_install</h3>
<p>Benefits over <code>pip_install</code>:</p>
<ul><li>10-100x faster dependency resolution</li><li>Better reproducibility</li><li>More reliable conflict resolution</li><li>Lockfile support</li></ul>
<pre><code class="lang-python"># ❌ SLOWER - Traditional pip
image = modal.Image.debian_slim().pip_install(
&quot;torch&quot;,
&quot;transformers&quot;
) # Can take minutes
# ✅ FASTER - uv
image = modal.Image.debian_slim().uv_pip_install(
&quot;torch&quot;,
&quot;transformers&quot;
) # Takes seconds</code></pre>
<h2>System Dependencies</h2>
<h3>apt_install</h3>
<p>Install system packages:</p>
<pre><code class="lang-python"># Single package
image = modal.Image.debian_slim().apt_install(&quot;ffmpeg&quot;)
# Multiple packages
image = modal.Image.debian_slim().apt_install(
&quot;ffmpeg&quot;,
&quot;libsm6&quot;,
&quot;libxext6&quot;,
&quot;libxrender-dev&quot;,
&quot;libgomp1&quot;
)
# Common combinations
# For OpenCV
opencv_image = (
modal.Image.debian_slim()
.apt_install(&quot;libsm6&quot;, &quot;libxext6&quot;, &quot;libxrender-dev&quot;)
.uv_pip_install(&quot;opencv-python&quot;)
)
# For audio processing
audio_image = (
modal.Image.debian_slim()
.apt_install(&quot;ffmpeg&quot;, &quot;libsndfile1&quot;)
.uv_pip_install(&quot;librosa&quot;, &quot;soundfile&quot;)
)</code></pre>
<h2>Custom Commands</h2>
<h3>run_commands</h3>
<p>Execute arbitrary shell commands:</p>
<pre><code class="lang-python"># Download and setup model
image = (
modal.Image.debian_slim()
.uv_pip_install(&quot;torch&quot;)
.run_commands(
&quot;mkdir -p /models&quot;,
&quot;wget https://example.com/model.bin -O /models/model.bin&quot;
)
)
# Build from source
image = (
modal.Image.debian_slim()
.apt_install(&quot;build-essential&quot;, &quot;cmake&quot;)
.run_commands(
&quot;git clone https://github.com/example/lib.git&quot;,
&quot;cd lib &amp;&amp; mkdir build &amp;&amp; cd build&quot;,
&quot;cmake .. &amp;&amp; make &amp;&amp; make install&quot;
)
)
# Environment setup
image = (
modal.Image.debian_slim()
.run_commands(
&quot;export PATH=/custom/bin:$PATH&quot;,
&quot;echo &#x27;export PATH=/custom/bin:$PATH&#x27; &gt;&gt; /root/.bashrc&quot;
)
)</code></pre>
<h2>Layering and Caching</h2>
<h3>Build Layers Efficiently</h3>
<p>Order operations for optimal caching:</p>
<pre><code class="lang-python"># ✅ GOOD - System deps first (change rarely)
image = (
modal.Image.debian_slim()
.apt_install(&quot;ffmpeg&quot;, &quot;libsm6&quot;) # Cached
.uv_pip_install(&quot;opencv-python&quot;) # Cached if deps unchanged
.copy_local_file(&quot;config.yaml&quot;, &quot;/app/config.yaml&quot;) # Changes often
)
# ❌ BAD - Frequently changing layers first
image = (
modal.Image.debian_slim()
.copy_local_file(&quot;config.yaml&quot;, &quot;/app/config.yaml&quot;) # Invalidates cache!
.apt_install(&quot;ffmpeg&quot;) # Has to rebuild every time
.uv_pip_install(&quot;opencv-python&quot;)
)</code></pre>
<h3>Separate Concerns</h3>
<p>Split rarely-changing from frequently-changing:</p>
<pre><code class="lang-python"># Base image (changes rarely)
base_image = (
modal.Image.debian_slim()
.apt_install(&quot;ffmpeg&quot;, &quot;libsm6&quot;)
.uv_pip_install(
&quot;torch==2.1.0&quot;,
&quot;transformers==4.35.0&quot;
)
)
# App image (changes frequently)
app_image = (
base_image
.copy_local_dir(&quot;./src&quot;, &quot;/app/src&quot;)
.copy_local_file(&quot;config.yaml&quot;, &quot;/app/config.yaml&quot;)
)
@app.function(image=app_image)
def my_function():
pass</code></pre>
<h2>Environment Variables</h2>
<h3>Set Build-Time Variables</h3>
<p>Configure environment during build:</p>
<pre><code class="lang-python">image = (
modal.Image.debian_slim()
.env({&quot;HF_HOME&quot;: &quot;/models/cache&quot;})
.uv_pip_install(&quot;transformers&quot;)
)
# Multiple variables
image = (
modal.Image.debian_slim()
.env({
&quot;TRANSFORMERS_CACHE&quot;: &quot;/models/transformers&quot;,
&quot;HF_HOME&quot;: &quot;/models/huggingface&quot;,
&quot;TORCH_HOME&quot;: &quot;/models/torch&quot;
})
)</code></pre>
<h2>Copying Local Files</h2>
<h3>copy_local_file and copy_local_dir</h3>
<p>Include local files in image:</p>
<pre><code class="lang-python"># Single file
image = (
modal.Image.debian_slim()
.copy_local_file(&quot;config.yaml&quot;, &quot;/app/config.yaml&quot;)
)
# Directory
image = (
modal.Image.debian_slim()
.copy_local_dir(&quot;./src&quot;, &quot;/app/src&quot;)
.copy_local_dir(&quot;./data&quot;, &quot;/app/data&quot;)
)
# With .gitignore-like filtering
image = (
modal.Image.debian_slim()
.copy_local_dir(
&quot;./src&quot;,
&quot;/app/src&quot;,
ignore=[&quot;*.pyc&quot;, &quot;__pycache__&quot;, &quot;*.log&quot;]
)
)</code></pre>
<h2>Dockerfile Integration</h2>
<h3>From Dockerfile</h3>
<p>Use existing Dockerfiles:</p>
<pre><code class="lang-python"># From Dockerfile in repo
image = modal.Image.from_dockerfile(&quot;Dockerfile&quot;)
# From Dockerfile with context
image = modal.Image.from_dockerfile(
&quot;docker/Dockerfile&quot;,
context_mount=modal.Mount.from_local_dir(&quot;.&quot;, remote_path=&quot;/context&quot;)
)
# From Dockerfile with build args
image = modal.Image.from_dockerfile(
&quot;Dockerfile&quot;,
build_args={&quot;PYTHON_VERSION&quot;: &quot;3.11&quot;}
)</code></pre>
<h2>Complete Examples</h2>
<h3>ML Image</h3>
<p>Comprehensive ML environment:</p>
<pre><code class="lang-python">ml_image = (
modal.Image.debian_slim(python_version=&quot;3.11&quot;)
.apt_install(
&quot;git&quot;,
&quot;wget&quot;,
&quot;libsm6&quot;,
&quot;libxext6&quot;
)
.uv_pip_install(
&quot;torch==2.1.0&quot;,
&quot;torchvision==0.16.0&quot;,
&quot;transformers==4.35.0&quot;,
&quot;accelerate==0.24.0&quot;,
&quot;bitsandbytes==0.41.0&quot;,
&quot;datasets==2.14.0&quot;,
&quot;evaluate==0.4.1&quot;,
&quot;tensorboard==2.15.0&quot;
)
.env({
&quot;HF_HOME&quot;: &quot;/cache/huggingface&quot;,
&quot;TORCH_HOME&quot;: &quot;/cache/torch&quot;
})
)</code></pre>
<h3>Data Processing Image</h3>
<p>ETL/data science environment:</p>
<pre><code class="lang-python">data_image = (
modal.Image.debian_slim(python_version=&quot;3.11&quot;)
.apt_install(&quot;postgresql-client&quot;, &quot;libpq-dev&quot;)
.uv_pip_install(
&quot;pandas==2.1.0&quot;,
&quot;numpy==1.24.0&quot;,
&quot;sqlalchemy==2.0.0&quot;,
&quot;psycopg2-binary==2.9.9&quot;,
&quot;pyarrow==13.0.0&quot;,
&quot;duckdb==0.9.0&quot;
)
)</code></pre>
<h3>Web Scraping Image</h3>
<p>Browser automation environment:</p>
<pre><code class="lang-python">scraping_image = (
modal.Image.debian_slim()
.apt_install(
&quot;chromium&quot;,
&quot;chromium-driver&quot;
)
.uv_pip_install(
&quot;selenium==4.15.0&quot;,
&quot;beautifulsoup4==4.12.0&quot;,
&quot;requests==2.31.0&quot;,
&quot;lxml==4.9.0&quot;
)
)</code></pre>
<h2>Debugging Images</h2>
<h3>Interactive Debugging</h3>
<p>Test image builds:</p>
<pre><code class="lang-python">@app.function(image=my_image)
def debug_image():
import subprocess
import sys
# Check Python version
print(f&quot;Python: {sys.version}&quot;)
# Check installed packages
result = subprocess.run(
[&quot;pip&quot;, &quot;list&quot;],
capture_output=True,
text=True
)
print(result.stdout)
# Check system packages
result = subprocess.run(
[&quot;dpkg&quot;, &quot;-l&quot;],
capture_output=True,
text=True
)
print(result.stdout[:1000]) # First 1000 chars
return &quot;Debug complete&quot;</code></pre>
<h2>Anti-Patterns to Avoid</h2>
<p><strong>DON&#x27;T use pip_install when uv_pip_install works:</strong></p>
<pre><code class="lang-python"># ❌ SLOW
image = modal.Image.debian_slim().pip_install(&quot;torch&quot;, &quot;transformers&quot;)
# ✅ FAST
image = modal.Image.debian_slim().uv_pip_install(&quot;torch&quot;, &quot;transformers&quot;)</code></pre>
<p><strong>DON&#x27;T copy unnecessary files:</strong></p>
<pre><code class="lang-python"># ❌ BAD - Copies everything including .git, node_modules
image = modal.Image.debian_slim().copy_local_dir(&quot;.&quot;, &quot;/app&quot;)
# ✅ GOOD - Only copy what&#x27;s needed
image = (
modal.Image.debian_slim()
.copy_local_dir(
&quot;./src&quot;,
&quot;/app/src&quot;,
ignore=[&quot;*.pyc&quot;, &quot;__pycache__&quot;, &quot;.git&quot;, &quot;node_modules&quot;]
)
)</code></pre>
<p><strong>DON&#x27;T install packages without versions in production:</strong></p>
<pre><code class="lang-python"># ❌ BAD - Non-reproducible
image = modal.Image.debian_slim().uv_pip_install(&quot;torch&quot;, &quot;transformers&quot;)
# ✅ GOOD - Pinned versions
image = modal.Image.debian_slim().uv_pip_install(
&quot;torch==2.1.0&quot;,
&quot;transformers==4.35.0&quot;
)</code></pre>
<p><strong>DON&#x27;T put changing layers early:</strong></p>
<pre><code class="lang-python"># ❌ BAD - Invalidates cache on every code change
image = (
modal.Image.debian_slim()
.copy_local_dir(&quot;./src&quot;, &quot;/app&quot;) # Changes often!
.uv_pip_install(&quot;torch&quot;) # Has to rebuild
)
# ✅ GOOD - Stable layers first
image = (
modal.Image.debian_slim()
.uv_pip_install(&quot;torch&quot;) # Cached
.copy_local_dir(&quot;./src&quot;, &quot;/app&quot;) # Only this rebuilds
)</code></pre>
<h2>Related Skills</h2>
<ul><li><strong>modal-functions-basics.md</strong> - Using images in functions</li><li><strong>modal-gpu-workloads.md</strong> - ML/GPU-specific images</li><li><strong>modal-volumes-secrets.md</strong> - Baking data vs volumes</li></ul>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/modal-image-building.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>