What is a Python Docker multi-stage build and why do single-stage images bloat?

A multi-stage build splits one Dockerfile into at least two stages. The builder stage has everything needed to resolve and compile dependencies. The runtime stage starts again from a clean base and receives only the finished artifact, either a virtual environment such as /opt/venv or a directory of built wheels. Anything you don't explicitly copy across never reaches the final image.

In a single-stage image, every layer you create stays in the image, even if a later step deletes files. A typical build that compiles psycopg, cryptography or numpy from source leaves behind:

  • gcc, make and the linker toolchain
  • -dev header packages such as libpq-dev and libssl-dev
  • Build backends and tools that the service never imports
  • pip or uv download and wheel caches
  • The full source tree, including tests and .git if the build context isn't filtered

Backend and platform engineers who ship services with native dependencies get the most from this split. Those are the images where compilers and headers make up a large share of the size and attack surface.

+------------------------- builder --------------------------+
|  compilers, -dev headers, uv, caches, source tree          |
|          uv sync / build  -->  /opt/venv  or  wheels/      |
+----------------------------|-------------------------------+
                             |  COPY --from=builder (artifact only)
                             v
+------------------------- runtime --------------------------+
|  slim base + runtime shared libs + /opt/venv + app code    |
+------------------------------------------------------------+

The base image tag helps, but it isn't what makes the final image small. A -slim base with a careless COPY . . and a leftover cache can end up larger than a full base built with discipline. The size comes from what you refuse to copy into the runtime stage.

+--------------------------- STAGE 1: builder ---------------------------+
|  full python base                                                      |
|  + gcc, make, linker        + libpq-dev, libssl-dev                    |
|  + uv, build backends       + uv/pip download caches                   |
|  + source tree: pyproject.toml, uv.lock, src/, tests/, .git            |
|                                                                        |
|     uv sync / uv build  ----->  [ /opt/venv ]  or  [ wheels/ ]         |
+---------------------------------------+--------------------------------+
                                        |
      NOT copied across:                |  COPY --from=builder
      compilers, -dev headers,          |  (artifact only)
      uv, caches, tests, .git           |
      (stay in builder stage)           v
+--------------------------- STAGE 2: runtime ---------------------------+
|  python -slim base                                                     |
|  + runtime shared libs only (e.g. libpq5, no -dev headers)             |
|  + /opt/venv  (or packages installed from builder's wheels/)           |
|  + app code, filtered by .dockerignore                                 |
|                                                                        |
|  CMD  /opt/venv/bin/python -m app                                      |
+------------------------------------------------------------------------+

The builder stage holds the toolchain, headers, caches and source tree. Only /opt/venv or wheels/ is copied into the slim runtime stage, so everything else stays out of the final image.

How do you structure the builder stage with uv?

The builder is the stage you plan to throw away, so it is where all the heavy tooling goes. Start from the Debian -slim variant of the official Python image, and pin it to the same Python minor version your runtime stage will use. A virtual environment records the absolute path of its interpreter, so a mismatch between builder and runtime breaks it. Install build-essential and only the -dev header packages your dependencies actually compile against, such as libpq-dev for a PostgreSQL driver built from source. None of this reaches the final image, so you don't have to slim this stage.

Bring in uv by copying its static binary from uv's published container image with COPY --from. Pin a specific tag so the toolchain doesn't drift between builds. Point the project environment at a fixed path like /opt/venv using the UV_PROJECT_ENVIRONMENT variable. A predictable location gives the runtime stage a single directory to copy and a single entry to add to PATH.

Layer order determines which steps rebuild. Docker reruns every step after the first one whose inputs changed:

  1. Copy only pyproject.toml and uv.lock.
  2. Run uv sync --locked --no-install-project to install dependencies without your code.
  3. Copy the source.
  4. Run uv sync --locked again to install the project itself.

With this order, editing application code invalidates only the last two steps, and the expensive dependency layer stays cached.

--locked makes the build fail if the lockfile doesn't match pyproject.toml, instead of silently re-resolving to versions nobody reviewed. uv changes quickly, so check these flags and environment variables against the documentation for the version you have pinned.

# syntax=docker/dockerfile:1
# Builder stage: heavy tooling lives here and is discarded later.
# Use the same Python minor version (3.12) as the runtime stage.
FROM python:3.12-slim-bookworm AS builder

# Compilers and headers only for packages built from source.
# No cleanup needed: this stage never ships.
RUN apt-get update \
 && apt-get install -y --no-install-recommends build-essential libpq-dev

# Copy the static uv binary from uv's image. Pin a tag you have tested.
COPY --from=ghcr.io/astral-sh/uv:0.5.11 /uv /usr/local/bin/uv

# Fixed venv path gives the runtime stage one directory to copy.
# Copy mode avoids hardlink warnings when the cache is a separate mount.
ENV UV_PROJECT_ENVIRONMENT=/opt/venv \
 UV_COMPILE_BYTECODE=1 \
 UV_LINK_MODE=copy

WORKDIR /app

# 1. Dependency metadata only, so this layer survives code edits.
COPY pyproject.toml uv.lock ./

# 2. Install dependencies, not the project. --locked fails the build
# if uv.lock is out of date instead of re-resolving.
RUN --mount=type=cache,target=/root/.cache/uv \
 uv sync --locked --no-install-project --no-dev

# 3. Source changes only invalidate the layers from here down.
COPY . .

# 4. Install the project itself. --no-editable puts it in the venv
# rather than linking back to /app.
RUN --mount=type=cache,target=/root/.cache/uv \
 uv sync --locked --no-dev --no-editable

A builder stage that installs build tools, copies a pinned uv binary, creates the venv at /opt/venv, and orders layers so locked dependencies install before the source is copied. Check each flag and environment variable against the documentation for your pinned uv version.

How do BuildKit cache mounts speed up uv and wheel caching?

A cache mount gives a RUN instruction a directory that BuildKit keeps between builds but never writes into the image. Point it at uv's cache (by default /root/.cache/uv when building as root, or wherever UV_CACHE_DIR points) and every wheel uv downloads or compiles from an sdist stays on the build host. When the lockfile changes, only the new or changed packages are fetched. Everything else installs from local disk.

The common alternative is to warm a cache in an earlier RUN and let it be committed. That fails in two ways. The cache becomes part of a layer, so it ships in the image or bloats the builder. It also lives inside that layer's cache key, so any change upstream of it, such as an edited uv.lock, invalidates the layer and discards the cache when you need it most. A mount is not part of the layer key, so it survives those invalidations.

Because the cache mount and the virtual environment are on different filesystems, uv can't hardlink from one to the other. Set UV_LINK_MODE=copy so uv copies files without warning about it.

The gain depends on the cache surviving between builds. On developer laptops and long-lived self-hosted runners it does. On ephemeral CI runners each job starts with an empty mount. Registry or CI layer-cache exports do not carry cache-mount contents, so you need a persistent builder or an explicit step that saves and restores the cache directory.

Illustrative estimate (assumed, not measured): 90 seconds saved per dependency rebuild, 10 rebuilds per engineer per day, 8 engineers, which comes to about two engineer-hours a day.

# syntax=docker/dockerfile:1
FROM python:3.12-slim AS builder

# Copy the uv binaries from the official image (pin a specific tag in real builds)
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

# The cache mount and /app/.venv are on different filesystems, so copy instead of hardlink.
# Compile bytecode at build time so the runtime image doesn't do it on first import.
ENV UV_LINK_MODE=copy \
    UV_COMPILE_BYTECODE=1 \
    UV_CACHE_DIR=/root/.cache/uv

WORKDIR /app

# Install dependencies only. The uv cache lives in a BuildKit cache mount:
# it persists on this builder across builds but is never written into a layer.
# Bind-mounting the lock and project files avoids a COPY layer for them here.
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --locked --no-install-project --no-dev

# Copy the source and install the project itself, reusing the same cache
COPY . /app
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked --no-dev

FROM python:3.12-slim

# Only the virtual environment and source ship; the uv cache stays on the build host
COPY --from=builder /app /app
ENV PATH="/app/.venv/bin:$PATH"
WORKDIR /app

CMD ["python", "-m", "myapp"]

A multi-stage Dockerfile that points a BuildKit cache mount at uv's cache directory, so downloaded and built wheels are reused across builds on the same builder without ending up in any image layer.

Should you copy the virtual environment or install prebuilt wheels in the runtime stage?

Copying the environment is the shorter path. The builder creates /opt/venv, the runtime stage runs COPY --from=builder /opt/venv /opt/venv, and then sets ENV PATH="/opt/venv/bin:$PATH". Setting PATH works better than source activate because each RUN and the container entrypoint start a fresh shell, so activation does not persist between steps. The approach is fragile, though. A venv is not relocatable. pyvenv.cfg records the absolute path of the base interpreter, and console scripts in bin/ have shebangs that point at the venv's own python. Compiled extensions are linked against the builder's libc. If any of those details differ between the stages, the image builds but fails at runtime.

The wheel approach moves artifacts instead of an installed tree. The builder runs pip wheel -r requirements.txt -w /wheels, or uv build for your own package. The runtime stage copies /wheels and installs offline with pip install --no-index --find-links /wheels <package>, or with the equivalent uv pip install flags. The runtime stage needs an installer and an extra layer. You can drop the wheel directory afterwards with a bind mount instead of a COPY.

Concern Copy /opt/venv Install prebuilt wheels
Python version and interpreter path must match Yes Version and ABI only
libc family must match (glibc vs musl) Yes Yes, for compiled wheels
Venv path must be identical Yes No
Installer needed in runtime No Yes
Dockerfile complexity Low Moderate

Copy the venv when both stages use the same base image family and tag. Use wheels when the runtime base differs, or when you want to publish the same artifacts to an internal index.

# syntax=docker/dockerfile:1
# Build one target: docker build --target runtime-venv .  (or runtime-wheels)

FROM python:3.12-slim AS builder
WORKDIR /src
COPY requirements.txt .
# Artifact for option A: an installed venv at a fixed absolute path
RUN python -m venv /opt/venv \
 && /opt/venv/bin/pip install --no-cache-dir -r requirements.txt
# Artifact for option B: one wheel per pinned dependency
RUN pip wheel --no-cache-dir -r requirements.txt -w /wheels

# Option A: copy the venv verbatim.
# Use the same image and tag as the builder so the interpreter path,
# Python version and libc (glibc here) all match.
FROM python:3.12-slim AS runtime-venv
COPY --from=builder /opt/venv /opt/venv
# Each RUN and the entrypoint start a new shell, so set PATH instead of activating
ENV PATH="/opt/venv/bin:$PATH"
WORKDIR /app
COPY app/ .
CMD ["python", "main.py"]

# Option B: install prebuilt wheels offline.
# The runtime base may differ, but it must have the same Python version/ABI
# and libc family as the builder for any compiled wheels to install.
FROM python:3.12-slim AS runtime-wheels
# Bind-mount the wheels for this step only, so they never become an image layer
RUN --mount=type=bind,from=builder,source=/wheels,target=/wheels \
    pip install --no-cache-dir --no-index --find-links /wheels /wheels/*.whl
WORKDIR /app
COPY app/ .
CMD ["python", "main.py"]

A single Dockerfile with two runtime targets: one copies /opt/venv and puts its bin directory on PATH, and the other installs builder-made wheels offline through a BuildKit bind mount, so the wheel files are not kept in the final image.

How do you harden and slim the runtime stage?

The runtime stage should contain only what the process needs at execution time. Compilers, headers and -dev packages belong in the builder. On Debian-based images, install libpq5 rather than libpq-dev: the compiled psycopg extension links against the shared library, not the headers. Run apt-get install with --no-install-recommends and delete /var/lib/apt/lists/* in the same layer. If you delete in a later layer, the files remain in the image.

Create a dedicated non-root user and switch to it with USER before CMD. If the application is compromised, the attacker gets that user's permissions instead of root. Make the user own only the directories it must write to.

Set two environment variables deliberately:

  • PYTHONUNBUFFERED=1 sends stdout and stderr straight to the container log driver. Without it, log lines can sit in a buffer and disappear when the process crashes.
  • PYTHONDONTWRITEBYTECODE=1 stops the interpreter from writing .pyc files at runtime. The container filesystem is usually ephemeral or read-only, so these writes are wasted.

The two variables interact with build-time compilation. Setting UV_COMPILE_BYTECODE=1 in the builder precompiles .pyc files, which removes compilation work from cold starts. The cost is a larger image and a longer build. This trade is usually worth it for short-lived workers and serverless-style deployments.

Add a .dockerignore that excludes .venv, .git, __pycache__, .pytest_cache, .mypy_cache, coverage output and test reports. Without it, a broad COPY . . can bring in a host virtual environment built for the wrong platform. Any change to those files also invalidates the layer cache on every build.

Pinning dependencies with a lockfile has an ongoing cost. Security patches only arrive when you regenerate the lock and rebuild on a fresh base image tag. Assign an owner and a schedule for both updates.

How do you verify image size and catch missing shared libraries?

Start by checking what actually shipped. docker image ls gives the total size of each tagged image, so compare the runtime image against the builder or a single-stage baseline. A runtime image close to the builder's size usually means a COPY --from pulled in more than the virtual environment. docker history <image> lists every layer with the instruction that created it and the size it added. Read it from the top down. Look for layers that install compilers or -dev packages, or that leave behind /root/.cache, uv's cache directory or a wheel directory you meant to discard. Content from BuildKit cache mounts never becomes part of a layer, so a large layer in that position points to a step that wrote its cache to the filesystem instead of the mount.

Size checks will not catch the more dangerous failure. A runtime stage can copy a complete virtual environment and build without errors, yet still lack a shared library that a compiled extension links against, such as libpq for a PostgreSQL driver or libxml2 for an XML parser. Nothing loads those .so files until Python imports the module, so the error surfaces as an ImportError at startup. If the module is imported lazily, it may only surface on the first request that reaches that code path.

Add a smoke test that runs the runtime image itself and explicitly imports every package with a native extension. Do not rely on starting the app, because lazily imported modules would be skipped. Run it in CI after the build and before the push, and fail the pipeline on a non-zero exit. In CI, a missing library is a one-line traceback next to the commit that caused it. After deployment, it is a crash-looping container, a rollback, and log searching to connect the failure to a base image or dependency change.

When should you avoid Alpine, distroless or multi-stage builds, and what are the alternatives?

Base image choice decides how often that failure mode shows up.

Alpine looks attractive because its base layer is small, but it uses musl instead of glibc. PyPI wheel coverage for musl is improving but still incomplete. When a dependency has no musl wheel, pip or uv falls back to building from source. That pulls compilers and headers into the builder, slows every cold build, and can produce a final image larger than the Debian slim equivalent. Behavioural differences in musl, such as DNS resolution and thread stack size, also cause bugs that do not reproduce on developer laptops. Use Debian slim unless you have checked that every dependency ships a musl wheel.

Distroless and other minimal runtime bases remove the shell, the package manager and most of userland. That shrinks the attack surface and the CVE scanner output. It also means you cannot exec into a container to inspect it, and adding a shared library requires copying it from another stage by hand. Teams that use these bases usually keep a debug variant or attach an ephemeral debug container.

A single-stage build is fine for pure-Python prototypes and internal tools where pull time and size do not matter. The second stage adds maintenance cost without much benefit there.

Option Size Wheel compatibility Debuggability Maintenance cost
Debian slim, multi-stage Small Broad (manylinux) Shell available Low
Alpine, multi-stage Small base, can grow Gaps in musl wheels Shell available Medium to high
Distroless runtime Smallest glibc, no package manager No shell High
Single-stage slim Larger Broad Full tooling Lowest

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to python docker multi-stage build, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Changing a shared variable is one edit and one review instead of editing every service's .env by hand.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.