Multi-stage Docker builds for Django with uv: builder, venv, and a slim runtime



A Django image built straight off pip install -r requirements.txt on a single stage drags along a C toolchain, pip's cache, and apt lists you only needed to compile psycopg[c]. Multi-stage plus uv gets rid of all of it: one stage resolves and installs dependencies into a venv, the other copies just that venv and the app code onto a slim base.

The Dockerfile

# syntax=docker/dockerfile:1
FROM python:3.13-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:0.5 /uv /usr/local/bin/uv
WORKDIR /app
ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-install-project --no-dev
COPY . .
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-dev

FROM python:3.13-slim AS runtime
RUN groupadd -r app && useradd -r -g app app
WORKDIR /app
COPY --from=builder --chown=app:app /app/.venv /app/.venv
COPY --from=builder --chown=app:app /app /app
ENV PATH="/app/.venv/bin:$PATH" PYTHONUNBUFFERED=1
USER app
EXPOSE 8000
CMD ["gunicorn", "config.wsgi:application", "--bind", "0.0.0.0:8000"]
Builder stage and runtime stage for a Django image with uvbuilderpython:3.13-slim+ uvCOPY pyproject.toml uv.lockRUN uv sync --frozen --no-devproduces /app/.venv~210 MB, discarded after buildruntimepython:3.13-slimCOPY --from=builder /app/.venvCOPY . .ENV PATH=/app/.venv/bin:$PATHCMD gunicorn config.wsgi~140 MB final imagevenv only

Why the two RUN steps for uv sync

The first uv sync --no-install-project installs only third-party dependencies, before COPY . . brings in your app code. That means editing a view or a template doesn't invalidate the dependency layer -- Docker's cache keys off the Dockerfile instruction and the files it reads, and pyproject.toml/uv.lock haven't changed. The second uv sync installs your own package in editable mode once the code is there. Skip the split and every rebuild reinstalls Django, psycopg and friends from scratch.

Layer caching tips that actually move the needle

  • Copy pyproject.toml and uv.lock before COPY . ., always. This is the single biggest win -- it's the difference between a 2-3 second rebuild and a 40+ second one on every code change.
  • Mount uv's own cache with --mount=type=cache,target=/root/.cache/uv. uv caches wheels per-version, so even a cold layer cache reuses the download across builds on the same machine or CI runner with cache persistence enabled.
  • Pin the uv version you copy in (uv:0.5 above, not :latest) -- an upstream uv release bump shouldn't silently invalidate every layer below it on your next build.
  • UV_COMPILE_BYTECODE=1 precompiles .pyc files at build time instead of on first request in the runtime container, worth it once you're running more than one replica.
  • Don't copy uv itself into the runtime stage. The builder needs it, the runtime container only needs the interpreter inside the venv and never calls uv again.

What this gets you

On our own CI, the before/after looks like this: a cold build (no cache at all) took 51 seconds with pip and a single stage, final image 480 MB. Switching to the two-stage uv build above: cold build 34 seconds, final image 142 MB, and a rebuild that only touches application code -- no dependency change -- finishes in about 2.5 seconds because every layer up to COPY . . is cache-hit. That's the number that actually matters day to day: how long you wait between saving a file and seeing it running in a container.

Leave a comment

Anonymous comments are published after review.