Docker multi-stage build for Python with uv

<p>Python Docker images are large (1GB+) because they include build tools, pip cache, and development packages. Need a lean production image while keeping a full dev environment. Using uv for fast dependency management.</p>

<p>Three-stage build: deps (build), dev (for local), prod (for deployment):</p> <div class="highlight"><pre><span></span><code><span class="c"># Dockerfile</span> <span class="k">FROM</span><span class="w"> </span><span class="s">python:3.12-slim</span><span class="w"> </span><span class="k">AS</span><span class="w"> </span><span class="s">base</span> <span class="k">WORKDIR</span><span class="w"> </span><span class="s">/app</span> <span class="c"># Install uv</span> <span class="k">COPY</span><span class="w"> </span>--from<span class="o">=</span>ghcr.io/astral-sh/uv:0.5<span class="w"> </span>/uv<span class="w"> </span>/uvx<span class="w"> </span>/usr/local/bin/ <span class="c"># Dependencies stage (cached unless pyproject.toml changes)</span> <span class="k">FROM</span><span class="w"> </span><span class="s">base</span><span class="w"> </span><span class="k">AS</span><span class="w"> </span><span class="s">deps</span> <span class="k">COPY</span><span class="w"> </span>pyproject.toml<span class="w"> </span>uv.lock<span class="w"> </span>./ <span class="k">RUN</span><span class="w"> </span>uv<span class="w"> </span>sync<span class="w"> </span>--frozen<span class="w"> </span>--no-install-project<span class="w"> </span>--no-dev <span class="c"># Development stage</span> <span class="k">FROM</span><span class="w"> </span><span class="s">deps</span><span class="w"> </span><span class="k">AS</span><span class="w"> </span><span class="s">dev</span> <span class="k">RUN</span><span class="w"> </span>uv<span class="w"> </span>sync<span class="w"> </span>--frozen<span class="w"> </span>--no-install-project<span class="w"> </span>#<span class="w"> </span>installs<span class="w"> </span>dev<span class="w"> </span>deps<span class="w"> </span>too <span class="k">COPY</span><span class="w"> </span>.<span class="w"> </span>. <span class="k">CMD</span><span class="w"> </span><span class="p">[</span><span class="s2">"uv"</span><span class="p">,</span><span class="w"> </span><span class="s2">"run"</span><span class="p">,</span><span class="w"> </span><span class="s2">"uvicorn"</span><span class="p">,</span><span class="w"> </span><span class="s2">"app.main:app"</span><span class="p">,</span><span class="w"> </span><span class="s2">"--host"</span><span class="p">,</span><span class="w"> </span><span class="s2">"0.0.0.0"</span><span class="p">,</span><span class="w"> </span><span class="s2">"--reload"</span><span class="p">]</span> <span class="c"># Production stage (lean)</span> <span class="k">FROM</span><span class="w"> </span><span class="s">base</span><span class="w"> </span><span class="k">AS</span><span class="w"> </span><span class="s">prod</span> <span class="c"># Copy only the virtual environment (no build tools, no uv)</span> <span class="k">COPY</span><span class="w"> </span>--from<span class="o">=</span>deps<span class="w"> </span>/app/.venv<span class="w"> </span>/app/.venv <span class="k">COPY</span><span class="w"> </span>.<span class="w"> </span>. <span class="c"># Activate venv</span> <span class="k">ENV</span><span class="w"> </span><span class="nv">PATH</span><span class="o">=</span><span class="s2">"/app/.venv/bin:</span><span class="nv">$PATH</span><span class="s2">"</span> <span class="c"># Run as non-root</span> <span class="k">RUN</span><span class="w"> </span>adduser<span class="w"> </span>--disabled-password<span class="w"> </span>--gecos<span class="w"> </span><span class="s1">''</span><span class="w"> </span>appuser<span class="w"> </span><span class="o">&amp;&amp;</span><span class="w"> </span>chown<span class="w"> </span>-R<span class="w"> </span>appuser<span class="w"> </span>/app <span class="k">USER</span><span class="w"> </span><span class="s">appuser</span> <span class="k">CMD</span><span class="w"> </span><span class="p">[</span><span class="s2">"uvicorn"</span><span class="p">,</span><span class="w"> </span><span class="s2">"app.main:app"</span><span class="p">,</span><span class="w"> </span><span class="s2">"--host"</span><span class="p">,</span><span class="w"> </span><span class="s2">"0.0.0.0"</span><span class="p">,</span><span class="w"> </span><span class="s2">"--port"</span><span class="p">,</span><span class="w"> </span><span class="s2">"8000"</span><span class="p">,</span><span class="w"> </span><span class="s2">"--workers"</span><span class="p">,</span><span class="w"> </span><span class="s2">"2"</span><span class="p">]</span> </code></pre></div> <div class="highlight"><pre><span></span><code><span class="c1"># Build specific stage</span> docker<span class="w"> </span>build<span class="w"> </span>--target<span class="w"> </span>prod<span class="w"> </span>-t<span class="w"> </span>myapp:latest<span class="w"> </span>. docker<span class="w"> </span>build<span class="w"> </span>--target<span class="w"> </span>dev<span class="w"> </span>-t<span class="w"> </span>myapp:dev<span class="w"> </span>. </code></pre></div> <p>The production image excludes uv, build tools, and dev dependencies. Only the <code>.venv</code> directory is copied. Result: ~200MB vs ~1GB+ naive build. Key: <code>--no-dev</code> in deps stage, then copy <code>.venv</code> directly to prod.</p>