Skip to content
Tutorials Center
My learning

Topics

Lesson 79 of 111 ยท Registries and CI/CD

Build Performance

Make Docker builds faster: measure first, shrink the build context, use cache mounts, run stages in parallel, share a remote cache and avoid common slowdowns.

A Docker build that takes ten minutes is not just annoying. It slows every code review, every CI run and every hotfix, and people start avoiding builds, which is how bugs reach production. Most slow builds are slow for a handful of repeatable reasons, and each has a cheap fix.

The rule of this lesson is measure first, then change one thing. You will learn how to read build timings, how to cut the build context, how cache mounts keep package downloads between builds, how BuildKit runs independent stages in parallel, and how to share a cache between machines. The numbers below come from real builds on one Windows laptop running Docker Desktop. Absolute times depend on your machine and network, so look at the relative differences.

Step zero: measure

The default build output redraws in place and hides most of what you need. Ask for the plain log:

CONSOLE
$ time docker build --progress=plain -t app .
#1 [internal] load build definition from Dockerfile
#1 DONE 0.1s
...
#7 [3/5] COPY requirements.txt .
#7 CACHED
#8 [4/5] RUN pip install -r requirements.txt
#8 DONE 11.7s
...
real    0m14.2s

Every step prints its own DONE 11.7s or CACHED. The slowest DONE is where you start. Three questions guide everything:

  1. Is the step cached when it should be? If not, the instruction order or the context is wrong (see The Build Cache).
  2. Is it slow because of the network? Downloads of packages and base images are the usual suspect.
  3. Is it slow because of the context? Look at the load build context step for a size and a time.

Keep a baseline. Before optimizing, run the build once from a fully cold state and once with a one-line code change. Those two numbers (cold build, warm rebuild) are what you are trying to improve, and you will know when you are done.

Shrink the build context

When the Dockerfile contains COPY . ., the client sends the whole context directory to the builder before the build can use it. Here is a project folder with a 115 MB data directory next to a one-line script and a Dockerfile that copies everything:

DOCKERFILE
FROM python:3.13-slim
WORKDIR /app
COPY . .
CMD ["python", "app.py"]
CONSOLE
$ docker build --progress=plain -t ctx-demo .
#4 [internal] load build context
#4 transferring context: 120.03MB 15.2s done
...
real    0m26.4s

Fifteen seconds were spent copying a data directory that the image does not even need. Add a .dockerignore file listing it:

TEXT
data
CONSOLE
$ docker build --progress=plain -t ctx-demo .
#4 [internal] load build context
#4 transferring context: 99B 0.0s done
...
real    0m2.0s

From 26 seconds to 2. The rule for .dockerignore is to ignore everything that is not part of the image: .git, node_modules, virtual environments, build output, local data, logs and secrets. The full syntax is in Build Context and .dockerignore.

An interesting detail: with the older COPY app.py ., BuildKit transferred just 27 bytes even though the huge directory sat in the same folder, because BuildKit only requests the files an instruction needs. COPY . . is what makes the whole directory relevant. So there are two fixes, and you should use both: ignore what you never need, and copy specific paths rather than everything.

Order instructions for the cache

Cache hits are free. A step that takes 12 seconds on a miss and 0 on a hit is the best optimization there is. The pattern is always the same: copy the dependency manifest, install, then copy the rest. If your Dockerfile still starts with COPY . . followed by an install, fix that before anything else. The details and per-language table are in The Build Cache.

Cache mounts: keep downloads between builds

The layer cache has one weakness. When the dependency list changes by even one package, the whole RUN pip install step is a miss, and pip downloads every package again. A cache mount gives a step a directory that survives between builds, outside of any image layer. Pip, npm, apt, Maven and Go all keep a download cache, and you can point that cache at a mount:

DOCKERFILE
# syntax=docker/dockerfile:1
FROM python:3.13-slim
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

To see the effect, build with two packages, add a third, and rebuild. With a plain RUN pip install --no-cache-dir, the second build downloads all three. With the cache mount:

CONSOLE
$ cat requirements.txt
flask==3.1.2
requests==2.32.4
itsdangerous==2.2.0
click==8.1.8
$ docker build --progress=plain -t cm-demo .
#9 4.368   Using cached flask-3.1.2-py3-none-any.whl.metadata (3.2 kB)
#9 4.431   Using cached requests-2.32.4-py3-none-any.whl.metadata (4.9 kB)
#9 4.449   Using cached itsdangerous-2.2.0-py3-none-any.whl.metadata (1.9 kB)
#9 4.717   Downloading click-8.1.8-py3-none-any.whl.metadata (2.3 kB)

Only the new package, click, is downloaded. The others come from the mounted pip cache. The mount does not become part of the image, so the image stays small, and you do not need --no-cache-dir any more.

Cache mounts are keyed by the mount's id (or its target path by default). Useful targets:

Tool Cache mount target
pip /root/.cache/pip
npm /root/.npm
uv /root/.cache/uv
Go modules and build cache /go/pkg/mod and /root/.cache/go-build
Maven /root/.m2
apt /var/cache/apt and /var/lib/apt (with sharing=locked)

The apt case needs one extra step, because Debian images delete downloaded packages automatically. A working example that keeps them:

DOCKERFILE
# syntax=docker/dockerfile:1
FROM debian:bookworm-slim
RUN rm -f /etc/apt/apt.conf.d/docker-clean \
 && echo 'Binary::apt::APT::Keep-Downloaded-Packages "true";' > /etc/apt/apt.conf.d/keep-cache
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update && apt-get install -y --no-install-recommends curl

sharing=locked makes two concurrent builds take turns instead of corrupting each other's apt state.

You can also mount the requirements file itself instead of copying it, so it never becomes a layer. This works because a bind mount only exists for that one command:

DOCKERFILE
RUN --mount=type=bind,source=requirements.txt,target=/tmp/requirements.txt \
    --mount=type=cache,target=/root/.cache/pip \
    pip install -r /tmp/requirements.txt

After the build, ls /tmp inside the container is empty: the file was visible only while pip ran. The cache mounts and their other cousins (secret and SSH mounts) are introduced in BuildKit and buildx.

A cache mount is a speed-up, never a source of truth. It can be empty (a fresh CI runner, after a prune), so a build must succeed without it. And it is not shared between machines. On throwaway CI runners you also need a remote cache, described below.

Parallel stages

BuildKit builds a Dockerfile as a graph, not a list. Stages that do not depend on each other run at the same time. A common use is a frontend build and a backend build that only meet at the end:

DOCKERFILE
FROM alpine:3.22 AS front
RUN sleep 9 && echo front > /front.txt

FROM alpine:3.22 AS back
RUN sleep 9 && echo back > /back.txt

FROM alpine:3.22
COPY --from=front /front.txt /srv/
COPY --from=back /back.txt /srv/

Here each sleep 9 stands in for a nine-second compile. Compare it to the same two steps written one after another in a single stage:

DOCKERFILE
FROM alpine:3.22
RUN sleep 9 && echo one > /one.txt
RUN sleep 9 && echo two > /two.txt
CONSOLE
$ time docker build -f Dockerfile.serial -t serial .
real    0m28.7s
$ time docker build -t parallel .
real    0m12.7s

The multi-stage version took about 13 seconds, the sequential one about 29 (the extra time on both is setup and export overhead on this machine). In the plain log of the parallel build, both RUN steps start together and finish after roughly ten seconds. So to speed up builds: split independent work into separate stages, and only combine them at the end with COPY --from. See Multi-Stage Builds.

BuildKit also skips stages the final target does not need. A test or debug stage that the last stage never copies from is not built at all, so extra stages cost nothing when you build the default target.

Share the cache between machines

The local cache disappears on a fresh machine. To reuse it you export it somewhere and import it again. Both directions have a flag:

CONSOLE
$ docker buildx build \
    --cache-to type=local,dest=./cache,mode=max \
    -t app .
...
#9 sending cache export 5.7s done
$ ls ./cache
blobs  index.json  ingest  oci-layout

On a different builder (an empty one, as on a new CI runner), import it:

CONSOLE
$ docker buildx build \
    --cache-from type=local,src=./cache \
    -t app .
#5 importing cache manifest from local:5765048792916974620
...
#8 [3/3] RUN pip install --no-cache-dir -r requirements.txt
#8 CACHED

The install step is CACHED on a builder that has never run it. A registry works the same way with type=registry,ref=registry.example.com/team/app:buildcache, and GitHub Actions has type=gha. Docker in CI shows complete pipelines. Two points to remember: mode=max exports every stage (the default only exports the final image's layers), and importing a big cache has its own cost, so measure that it helps.

Smaller images build and ship faster

Build time also includes pulling base images, exporting the result and pushing it. A smaller base (-slim, -alpine) and a multi-stage build that leaves compilers behind shrink all three. Keep an eye on what each layer adds:

CONSOLE
$ docker history --format '{{.Size}}\t{{.CreatedBy}}' app | head -4
0B      CMD ["python" "app.py"]
20.5kB  COPY . . # buildkit
8.19kB  WORKDIR /app

Choosing a Base Image explains the trade-offs, and Layers and the Union Filesystem explains why deleting a file in a later layer does not shrink the image.

A checklist of common slowdowns

Symptom Likely cause Fix
transferring context takes seconds Missing .dockerignore, COPY . . Ignore big folders, copy specific paths
Install step reruns on every code change Source copied before installing Copy manifest, install, then copy the rest
Install reruns and downloads everything One package changed Cache mount for the package manager
Total time is the sum of all stages Independent work in one stage Split into parallel stages
Every CI run starts from zero Empty runner --cache-from / --cache-to
apt-get update always runs RUN placed after a changing step Move system packages to the top
Base image pulled on every build --pull in a loop, or no local copy Pull only when you need to update

You can inspect and clean the shared build cache with docker buildx du and docker buildx prune (see Cleaning Up). Be careful on a shared machine: the cache belongs to every project that uses the builder, and cache mounts show up there too.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A build log shows transferring context: 120.03MB 15.2s done for a project whose image only needs one small script. What is the best fix?

    The time is spent sending the context to the builder. Ignoring what the image does not need (and not using COPY . . carelessly) removes it. The base image and the cache are not involved.
  2. 2. What does RUN --mount=type=cache,target=/root/.cache/pip pip install -r requirements.txt do differently from a plain RUN pip install?

    The cache mount directory lives outside the image. When a requirement changes, the step reruns but pip reuses already downloaded packages from the mount. It is never part of the layers.
  3. 3. Two independent stages each take about 10 seconds, and a final stage copies a file from each. How long does the build take if BuildKit is used?

    BuildKit builds a dependency graph. Stages that do not depend on each other start together. In our measurement the parallel version took about 13 seconds against about 29 for the same work written sequentially.
  4. 4. A brand-new CI runner has no layer cache. Which option lets it reuse the cache from earlier builds?

    --cache-to exports the cache to a registry, directory or CI cache, and --cache-from imports it on another machine. The other options do not carry cache between machines.
  5. 5. Why should a build still succeed when the cache mount is empty?

    Cache mounts live in the builder, not in your image or repository. A pruned cache or a fresh runner starts empty, so the build must work without it and only get faster with it.

Summary

  • Measure first: docker build --progress=plain prints the time of every step and marks CACHED ones. Keep a cold-build and a warm-rebuild baseline.
  • A big build context is the most common hidden cost. Use .dockerignore and copy specific paths; in our test, ignoring one data directory cut a build from 26 seconds to 2.
  • Order instructions so dependency installs are cached across code changes.
  • RUN --mount=type=cache keeps pip, npm, apt or Go download caches between builds without growing the image, and type=bind shows a file to one command without creating a layer.
  • Independent stages build in parallel; split frontend, backend and tool stages and join them with COPY --from. Stages the target does not need are skipped.
  • Share the cache between machines with --cache-to and --cache-from (registry, local directory or gha); use mode=max for multi-stage builds.
  • Smaller base images make pulling, exporting and pushing faster too.

Next: Deploying on a Single Host