Dockerfile layer caching optimization

<p>My Docker builds are slow because every code change invalidates the package installation layer. I need to structure my Dockerfile so that dependency installation is cached and only code changes trigger re-execution.</p>

<p>Optimize layer order for maximum cache hits:</p> <div class="highlight"><pre><span></span><code><span class="c"># BAD: Code copied first -- any change invalidates pip install</span> <span class="k">FROM</span><span class="w"> </span><span class="s">python:3.12-slim</span> <span class="k">COPY</span><span class="w"> </span>.<span class="w"> </span>/app<span class="w"> </span>#<span class="w"> </span>Every<span class="w"> </span>code<span class="w"> </span>change<span class="w"> </span>invalidates<span class="w"> </span>everything<span class="w"> </span>below <span class="k">RUN</span><span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>-r<span class="w"> </span>requirements.txt <span class="c"># GOOD: Dependencies before code</span> <span class="k">FROM</span><span class="w"> </span><span class="s">python:3.12-slim</span> <span class="k">WORKDIR</span><span class="w"> </span><span class="s">/app</span> <span class="c"># 1. System deps (changes rarely)</span> <span class="k">RUN</span><span class="w"> </span>apt-get<span class="w"> </span>update<span class="w"> </span><span class="o">&amp;&amp;</span><span class="w"> </span>apt-get<span class="w"> </span>install<span class="w"> </span>-y<span class="w"> </span>libpq-dev<span class="w"> </span><span class="o">&amp;&amp;</span><span class="w"> </span>rm<span class="w"> </span>-rf<span class="w"> </span>/var/lib/apt/lists/* <span class="c"># 2. Dependency files only (changes when you add packages)</span> <span class="k">COPY</span><span class="w"> </span>pyproject.toml<span class="w"> </span>uv.lock<span class="w"> </span>./ <span class="c"># 3. Install deps (cached if pyproject.toml/uv.lock unchanged)</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>/usr/local/bin/uv <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"># 4. Application code (changes frequently -- last)</span> <span class="k">COPY</span><span class="w"> </span>./app<span class="w"> </span>./app <span class="k">COPY</span><span class="w"> </span>./migrations<span class="w"> </span>./migrations <span class="c"># Layer ordering rule: least-frequently-changed first</span> </code></pre></div> <p>.dockerignore (critical for cache validity):</p> <div class="highlight"><pre><span></span><code>**/__pycache__ *.pyc .git/ tests/ *.md .env* .venv/ </code></pre></div> <p>Key points: - Docker caches layers -- a changed layer invalidates all subsequent layers - Copy package files (requirements.txt, uv.lock) before copying application code - System packages should be installed before Python packages - .dockerignore prevents irrelevant files from invalidating cache - Use RUN --mount=type=cache for pip cache between builds (BuildKit)</p>