Systems Measured

Your Docker Build Context Taxes Every Rebuild — Even the Cached Ones

Nothing changed. Both steps hit the cache. The image came out byte-identical. The only difference was 1 GB of files the Dockerfile never touches, and the rebuild still took about four times as long.

Written November 8, 2026 · 10 min read

By the end of this guide
  • The cached rebuild still pays for every byte
  • One line removes it
  • The context is not the image
  • Cold builds, with a warning

What this tutorial measures

A Docker build context is the set of files your build can access. The Docker docs define it that way, and add that a filesystem context is processed recursively, so every subdirectory is included. What the docs do not say is what that costs on a rebuild where nothing changed. This tutorial measures exactly that: the same Dockerfile, the same code, the same image, with only the unreferenced junk in the context changing.

The setup is deliberately boring. One Dockerfile, three lines:

Dockerfile
FROM busybox:stable
COPY hello.txt /hello.txt
CMD ["cat", "/hello.txt"]

The Dockerfile copies exactly one tiny file, so the junk is never referenced by any instruction. Four contexts differ only in unreferenced random files under a junk/ directory: tiny (no junk at all), medium (100 MB of junk), large (1 GB of junk), and large-ignored (the same 1 GB of junk, with a .dockerignore file containing one line, junk/). Per case, the probe ran one cold build under a fresh tag and then three cached rebuilds under the same tag with no changes, except large-ignored which ran two cached rebuilds. Fifteen builds in total, all exiting 0.

This box runs the classic builder: docker buildx answers unknown command, so plain docker build is the classic builder, which tars and sends the whole context before any step runs. The base image is busybox, already local.

The cached rebuild still pays for every byte

Every cached rebuild in both runs printed Using cache for both steps. Nothing executed. The image came out identical. The rebuild still slowed with context size:

Sent context Cached rebuilds, Nov 8 (seconds) Median Nov 8 Median Nov 7
3.072 kB 0.642 / 0.660 / 0.695 0.660 0.711
104.9 MB 0.794 / 0.846 / 0.882 0.846 1.153
1.049 GB 2.546 / 2.718 / 3.007 2.718 2.670
4.096 kB, junk ignored 0.618 / 0.649 0.634 0.683

The large context costs about two seconds on every no-change rebuild. Large versus tiny is 2.718 against 0.660 seconds on Nov 8, 4.12 times slower and 2.06 seconds longer, and 2.670 against 0.711 seconds on Nov 7, 3.76 times slower and 1.96 seconds longer. Two runs, same shape: about four times, about two seconds. Medium versus tiny is smaller, 1.28 times on Nov 8 and 1.62 times on Nov 7, so the tax scales with context size rather than appearing all at once.

The mechanism is visible in the build output. Every cached rebuild prints the context line first:

Output
Sending build context to Docker daemon  1.049GB
Using cache
Using cache
Successfully built ab6d0f4a8316

The classic builder sends the whole context before it evaluates the cache. The cache saves the work of the steps. It does not save the work of tarring, hashing, and sending a gigabyte of files the Dockerfile never touches. That send is the tax, and it is paid on every build, including the ones that change nothing.

One line removes it

The large-ignored case is the same 1 GB of junk with one line in .dockerignore:

Output
junk/

The Docker docs say files matching .dockerignore patterns are removed from the build context before it is sent to the builder, which improves build speed. The measurement agrees. The sent context falls from 1.049 GB to 4.096 kB, and the cached median falls from 2.718 seconds to 0.634 seconds on Nov 8, and from 2.670 to 0.683 seconds on Nov 7. That is 0.96 times the tiny median on both runs, the same as having no junk at all. The fix is one line, and the tax is gone, not reduced.

The usual .dockerignore advice is to exclude node_modules, .git, build output, and test data. The measurement gives that advice a number: every gigabyte left in the context costs about two seconds per rebuild, even when the rebuild is fully cached. A project rebuilt fifty times a day pays a hundred seconds a day for a gigabyte nobody reads.

The context is not the image

All fifteen builds in each run produced the same image. On Nov 8 the id was ab6d0f4a8316 for all fifteen; on Nov 7 it was c877057f213d for all fifteen. The image size was 4.42 MB in both runs, in all four cases. Running the tiny image and the large image both print the same line:

Output
hello from ctx probe

The junk never enters the image. The cost is purely on the build path. That is also why the usual image-size advice misses this problem: shrinking the image does nothing for the rebuild tax, because the tax is paid before the image exists. The closest existing measurement makes the same point from the cold side. HackerNoon measured a 1.42 GB context against an 18 MB one with .dockerignore and found the send time fell from 21.8 seconds to 0.4 seconds, with the final image unchanged at 412 MB in both cases. Their nearest rebuild row is a rebuild after a code change, a cache miss, at 3.1 seconds against 3.4 seconds. Near-identical, which is why the tax looks invisible until you hold the code constant and vary only the context. That is the gap this tutorial fills: same Dockerfile, same code, same image, only the junk changes.

Cold builds, with a warning

The cold builds are supporting color, not the claim, because cold numbers are noisy. On Nov 7: tiny 3.956 seconds, medium 1.880, large 5.439, large-ignored 0.655. Large against large-ignored is 8.30 times. But tiny ran first and its 3.956 seconds includes daemon warm-up, so it is slower than medium despite a 3 kB context. Do not quote the cold column as a clean comparison.

The Nov 8 cold runs were discarded outright. The tiny cold build reported 83.480 seconds, and the large-ignored cold build reported a negative wall time of 0.541 seconds. A negative elapsed time is impossible, so both numbers are artifacts of the clock jumping, the same class of artifact the systemd timer probe hit here. The cached rebuilds are unaffected: their ranges are tight on both runs, and the medians agree across the two days. The claim in this tutorial rests on the cached medians, not on the cold column.

What this does not cover

The large cached rebuilds varied: 4.149, 2.601, and 2.670 seconds on Nov 7, and 2.546, 2.718, and 3.007 seconds on Nov 8. The first cached run after the cold build was the slowest on Nov 7. This tutorial reports the median and the range, not a single figure, and the ratio is quoted as a range across the two runs, 3.76 to 4.12 times.

The numbers are for the classic builder, 32 CPUs with a local daemon. Over a remote builder or a slow network the transfer cost is larger, not smaller, but that is an inference, not a measurement, and this tutorial states no remote numbers. The Docker docs note that .dockerignore helps build speed especially with a remote builder, which is consistent with the inference but is not a measurement of it.

The junk was random bytes, which do not compress. A context of highly compressible text may transfer faster than the numbers here, because the tax measured here is tar plus hash plus send of 1 GB of random data. Say it plainly: these numbers are the worst shape, random data, not the average shape.

BuildKit is not measured here. The current Docker docs describe the builder loading only the files it needs from the build context when needed, which is BuildKit behavior, and the classic builder measured here sends the whole context first. Do not apply these numbers to BuildKit builds. A BuildKit re-measurement is a follow-on probe, not a claim to make without running it.

FAQ

Why does a cached rebuild send anything at all?

Because the classic builder tars and sends the whole context before it evaluates the cache. The build log shows it: the Sending build context line prints first, then both steps report Using cache. The cache decides whether the steps run. The send happens either way.

Does .dockerignore change the image?

No. The image was 4.42 MB with and without the ignore file, and both images print the same line when run. .dockerignore changes what is sent to the builder, not what is copied into the image. Only COPY and ADD put files in the image, and this Dockerfile copies one tiny file.

Do these numbers apply to BuildKit?

No. These numbers are for the classic builder, which is what docker build is on a box without buildx. BuildKit transfers files on demand, so its rebuild tax for the same context should be smaller, but that was not measured here. The scope is the builder actually measured.

What belongs in .dockerignore?

Anything the Dockerfile does not copy: node_modules, .git, build output, test data, local databases, editor files. The test is the first line of docker build output. If the sent context is larger than the files your Dockerfile copies, the difference is tax.

Is a two-second tax worth fixing?

Once, no. Fifty rebuilds a day, every day, yes, and it compounds with context size: the medium case already cost an extra 0.19 to 0.44 seconds per rebuild for 100 MB. The fix is one line, so the payback starts on the next build.

Sources

  • Docker, Build context — the build context as the set of files a build can access, recursive processing of subdirectories, .dockerignore removing files from the context before it is sent to the builder, and the builder loading only the files it needs when needed.
  • HackerNoon, How to Make Docker Builds Smaller and Faster — the nearest existing measurement: 1.42 GB context against 18 MB with .dockerignore, send time 21.8 seconds against 0.4 seconds, final image unchanged at 412 MB; its rebuild row is a cache miss after a code change, not a no-change cached rebuild.
  • Veldica, Deterministic Python Prose Tokenizer Library — the only other Veldica page that mentions Docker, on image size and cold-start times, the image-size side of the problem this tutorial does not cover.
Summary
  • A no-change, fully cached rebuild still sends the whole context on the classic builder. The cache saves the steps, not the send.
  • The tax scales with context size. A 1 GB context costs about two seconds per rebuild, about four times the tiny-context rebuild, on two separate runs.
  • .dockerignore removes the tax entirely. One line took the sent context from 1.049 GB to 4.096 kB and the cached median from 2.72 seconds to 0.63 seconds.
  • Context size and image size are separate problems. All fifteen builds produced the same 4.42 MB image. Shrinking the image does not fix the rebuild tax.
  • Measure the sent context, not the image. The first line of docker build output prints it. If it is larger than a few megabytes, those bytes are rebuild tax.

Keep Exploring