Docker rebuilds reuse recorded work, including stale work

Sun, 20 Feb 2028 00:00:00 +0000

Docker’s build cache stores results of build operations so a later build can reuse work whose relevant inputs still match. A cache hit does not mean the command ran again and produced identical output. It means the builder accepted an existing result. That distinction matters for package installation, generated timestamps, remote downloads, and any operation whose output could change without a corresponding change to its declared inputs.

When it breaks

An unchanged RUN apt-get update can reuse yesterday’s result without contacting a repository. The builder does not routinely inspect that remote repository to decide whether a cached RUN remains fresh. A successful cached build therefore provides no independent evidence that packages received the newest available security updates. Refresh policy must be deliberate and compatible with the project’s reproducibility requirements.

COPY has different inputs from a plain command string. File contents and relevant metadata participate in its cache calculation, but source modification time alone does not. A deployment script that merely touches a file can leave the dependent RUN cached. Conversely, changing an executable permission can invalidate a COPY even when the text remains identical, causing dependent work to execute again.

The base image, build arguments used by a step, and preceding dependencies also matter. Cache invalidation follows dependencies; treating a complex multistage build as one unavoidable linear rebuild can be misleading. In the simple single-stage chain below, changing the copied file invalidates the following timestamp-producing RUN, while the fixed base filesystem layers remain reusable.

Check it quickly

Run the script with host Python and access to a disposable Docker builder. Pull the named digest first if it is unavailable locally. The recorded run used Docker 29.3.1, Buildx 0.32.1, and a Linux arm64 Python 3.11.16 base. Builds and containers disable networking. Temporary tags are removed, but the script deliberately leaves unrelated images and builder caches alone:

from pathlib import Path
from tempfile import TemporaryDirectory
import json,os,shlex,subprocess,uuid

BASE='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(["docker",*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def inspect(image):return json.loads(docker("image","inspect",image).stdout)[0]

name='xbcatm-cache-'+uuid.uuid4().hex[:10];tag=name+':probe'
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);app=root/'app.txt';app.write_text('initial '+name);app.chmod(0o644)
 build_code="from pathlib import Path;import time;Path('/built-at').write_text(str(time.time_ns()))"
 (root/'Dockerfile').write_text(f'FROM {BASE}\nCOPY app.txt /app.txt\nRUN python -c {shlex.quote(build_code)}\n')
 def build(*options):return docker('build','--network','none','--progress','plain',*options,'-t',tag,str(root))
 def stamp():return docker('run','--rm','--network','none',tag,'python','-c',"from pathlib import Path;print(Path('/built-at').read_text())").stdout.strip()
 build();initial=stamp();base_layers=inspect(BASE)['RootFS']['Layers']
 result=build();assert stamp()==initial and 'CACHED' in result.stderr
 timestamp=app.stat().st_mtime_ns+10_000_000_000;os.utime(app,ns=(timestamp,timestamp))
 build();assert stamp()==initial
 print('unchanged inputs reuse the RUN result; changing only source mtime also leaves that result cached')
 app.chmod(0o755);build();mode_changed=stamp();assert mode_changed!=initial
 app.write_text('changed '+name);build();content_changed=stamp();assert content_changed!=mode_changed
 print('changing copied-file permissions or content invalidates COPY and reruns the dependent RUN')
 build('--no-cache');assert stamp()!=content_changed
 assert inspect(tag)['RootFS']['Layers'][:len(base_layers)]==base_layers
 print('no-cache reruns the instruction while this pinned base retains the same filesystem layer prefix')
finally:docker('image','rm',tag,check=False)

The first build writes a nanosecond timestamp into /built-at. A second identical build reports a cached operation and returns exactly the same timestamp. This is stronger evidence than comparing elapsed build times: a quick build could still have executed the command, while the retained timestamp identifies the already-recorded result that was reused.

The script then advances only the source file’s modification time. The timestamp inside the image remains unchanged. This demonstrates the documented mtime exclusion directly; it does not imply that all filesystem metadata is ignored. The following change from mode 0644 to 0755 causes a new timestamp, establishing that the executable-bit difference affects this COPY dependency.

Changing the file’s text produces another timestamp. The test uses a uniquely named input so an old experiment cannot accidentally supply the initial application result. Its assertions compare actual image contents after each build, rather than treating a generic CACHED message somewhere in the build log as proof that the particular operation under discussion was reused.

Finally, --no-cache makes the RUN execute again with unchanged application inputs. Inspection still shows the same pinned base-layer prefix. This option disables reuse for build instructions; it does not replace an explicitly selected base digest with a newer one. Obtaining a changed base requires choosing the intended artifact, and floating-tag refresh has its own pull policy.

Make freshness an explicit input

Place stable dependency inputs before frequently edited source, and use narrow COPY instructions so unrelated files do not become dependencies. Pin package versions or verified artifacts when repeatability is required. For intentional dependency refreshes, update those declarations and review the resulting artifact instead of assuming that a cache miss is itself a security policy.

Secret mounts need separate attention: changing a secret’s contents does not automatically invalidate the build cache. If the secret controls a fetch whose output must be refreshed, use a documented nonsecret revision input or explicit invalidation. Never embed the credential in an argument merely to force a new cache key.

Treat cache-hit logs as performance evidence and executed tests as behavioral evidence. Record the final artifact identity, test it, and retain enough build inputs to explain how it was produced. A fast rebuild is useful only when the reused work is still the work the release intends to ship.

Sources

Docker build cache invalidation, cache inputs, modification times, RUN reuse, and explicit invalidation, checked 2026-09-12.
Dockerfile reference, COPY metadata, RUN instructions, and build arguments, checked 2026-09-12.

Image · XB Field Notes

Docker rebuilds reuse recorded work, including stale work

When it breaks

Check it quickly

Make freshness an explicit input

Sources