16.1.3.4 No Cache Rebuild

A no-cache rebuild, performed with docker build --no-cache, forces every instruction in a Dockerfile to execute fresh regardless of what Docker's layer cache would otherwise reuse, and it is one of the most useful and most frequently reached-for diagnostic tools in Docker troubleshooting precisely because it eliminates an entire category of possible explanation, stale caching, in a single step.

What --no-cache actually does

The flag instructs the builder to ignore every existing cached layer entirely and re-execute each instruction from scratch against the current build context and base image:

docker build --no-cache -t my-api .

This is distinct from simply deleting cached layers manually or pruning the build cache; --no-cache applies only to the specific build invocation it is passed to, leaving the existing cache intact for any future build that does not also specify it.

When to reach for it during troubleshooting

A no-cache rebuild is the appropriate first diagnostic step whenever a build's behavior seems inconsistent with what the current Dockerfile and source code should produce, since it immediately rules in or out stale caching as the explanation:

docker build --no-cache -t my-api:fresh .
docker build -t my-api:cached .
diff <(docker run --rm my-api:fresh cat /app/version.txt) <(docker run --rm my-api:cached cat /app/version.txt)

If a no-cache rebuild produces a meaningfully different result than the cached one, the difference is direct, conclusive evidence that caching was indeed serving stale content for at least one instruction; if the two are identical, caching can be ruled out as the explanation and the investigation should move to a different layer entirely.

The cost of a no-cache rebuild

A full no-cache rebuild re-executes every instruction, including expensive ones like dependency installation, which can take considerably longer than a normal, cache-assisted build; this cost is the trade-off for the diagnostic certainty it provides, and it is worth being deliberate about when this cost is actually justified versus when a more targeted diagnostic step would answer the same question faster:

time docker build --no-cache -t my-api .
time docker build -t my-api .

For a build where only a specific, later instruction is suspected of serving stale content, selectively invalidating the cache from that point forward, rather than discarding everything from the very first instruction, can answer the same question at lower cost.

Targeted cache invalidation as a cheaper alternative

Rather than a full no-cache rebuild, a small, deliberate change to an early instruction forces cache invalidation from that point onward without discarding everything before it, which is useful when the suspected staleness is isolated to a specific, later part of the build:

ARG CACHE_BUST=1
RUN echo "cache bust: ${CACHE_BUST}"
RUN curl -sf https://example.com/install.sh | sh

docker build --build-arg CACHE_BUST=$(date +%s) -t my-api .

This targets exactly the suspected instruction and everything after it, while still allowing earlier, unrelated layers like dependency installation to be reused from cache, which is considerably faster than a full rebuild when the actual scope of suspected staleness is narrow.

Using --no-cache as routine maintenance, not just diagnosis

Beyond reactive troubleshooting, scheduling regular no-cache rebuilds as routine maintenance addresses the broader class of cache invalidation miss problems, stale base images, stale package repository state, before they manifest as a noticed problem at all:

0 3 * * 1 docker build --no-cache --pull -t my-api . && docker push registry.example.com/my-api:latest

A weekly scheduled no-cache, pull-forcing rebuild, even with no application code change, surfaces base image and dependency drift on a predictable cadence, rather than only when a security scan or an unrelated incident happens to draw attention to it.

Combining --no-cache with --pull

For diagnosing or preventing staleness comprehensively, combining --no-cache with --pull addresses both layers of potential staleness simultaneously, the build's own layer cache and the locally cached copy of the base image itself:

docker build --no-cache --pull -t my-api .

Using --no-cache alone still allows a stale, locally cached base image to be reused, since --no-cache only affects layers built from instructions in the Dockerfile, not the separate question of whether the base image referenced by FROM is itself current; --pull specifically addresses that separate concern.

Confirming a no-cache rebuild is actually fully fresh

For multi-stage builds, confirming that --no-cache applied to every stage, not just the final one, is worth verifying directly, since some build tooling or scripting around a multi-stage build can inadvertently scope a no-cache flag to only part of the overall build process:

docker build --no-cache --progress=plain -t my-api . 2>&1 | grep -c "CACHED"

A build output containing zero occurrences of "CACHED" confirms every instruction across every stage was genuinely re-executed; any remaining "CACHED" entries indicate the no-cache behavior did not apply as comprehensively as intended, worth investigating further before trusting the rebuild's result as fully representative of a clean build.

Common mistakes

• Reaching for a full no-cache rebuild for every build inconsistency investigation, when a more targeted, cheaper cache-busting technique would answer the same question faster.
• Using --no-cache without --pull, leaving a stale, locally cached base image untouched even though every other layer is rebuilt fresh.
• Assuming --no-cache was applied comprehensively across every stage of a multi-stage build without verifying directly through the build output.
• Treating a no-cache rebuild purely as a reactive diagnostic tool, rather than also scheduling it as routine, preventive maintenance.
• Not comparing the no-cache result against the cached version directly when investigating a suspected staleness issue, missing the most conclusive evidence available.

A no-cache rebuild is one of the most direct and conclusive troubleshooting tools available for Docker builds, immediately ruling in or out an entire category of possible cause, and pairing it with --pull and routine scheduling extends its value from a reactive diagnostic step into a proactive defense against the kind of silent staleness that Docker's caching model is structurally unable to detect on its own.