Intro
Docker layer caching turns repetitive image builds from minutes into seconds, but only when operators know how to observe, verify, and recover from cache behavior. This guide provides actionable commands and real examples for developers, DevOps consultants, and technical startup teams who need to build images reliably without wasting compute or debugging time.
The focus is operational safety: observe before changing, limit the blast radius, use placeholders instead of secrets, verify results, and document recovery paths. We cover version and environment inventory, safe configuration, verification and diagnostics, failure modes and recovery, an operations checklist, and common pitfalls. Each section includes concrete commands, expected outputs, and decision guidance.
Who this is for: you run docker build regularly, you have seen mysterious cache misses, or you need to prove that caching works before pushing to CI. If you already know Docker basics, this guide will sharpen your caching skills with practical, testable examples.
Version and Environment Inventory
Before touching caching, confirm your Docker and BuildKit versions. Docker 18.09+ ships BuildKit as an optional builder; Docker 23+ enables it by default. If you are on an older Docker version, many caching features will not exist or behave differently.
Read-only observations first:
# Check Docker client and server versions
docker version --format '{{.Client.Version}} {{.Server.Version}}'
# Check BuildKit support (Docker 18.09+)
docker buildx version
# List builders and see which one is active
docker buildx ls
Expected outputs:
docker versionshows both client and server versions. If only client appears, the daemon is unreachable or the user lacks permissions.docker buildx versionprints a version likegithub.com/docker/buildx v0.11.2if Buildx is installed.docker buildx lslists builders; the active one has an asterisk. The defaultdefaultbuilder uses the Docker daemon's BuildKit; a separatedocker-containerdriver is often used for advanced caching.
Check current build cache usage:
# Show disk usage by Docker, including build cache
docker system df
# Show detailed build cache usage (requires BuildKit)
docker buildx du
Sample docker system df:
TYPE TOTAL ACTIVE SIZE RECLAIMABLE
Images 15 12 3.2GB 1.1GB (34%)
Containers 3 1 100MB 0B (0%)
Local Volumes 5 5 1.2GB 0B (0%)
Build Cache 28 0 2.5GB 2.5GB (100%)
Here, build cache is fully reclaimable because no active build is using it. That is normal after builds finish.
Version-dependent feature check:
- If you need cache mounts (
RUN --mount=type=cache), you must use BuildKit. The classic builder ignores them. - If you want to ship cache to a registry for CI, you need
docker/build-push-actionwith Buildx and registry support.
Impact on layer caching:
- Docker layer caching is a builder-level feature. The daemon version and storage driver can affect cache lookup, but the builder determines how layers are created and reused.
- Because BuildKit is now the default, many guide assumptions (like
--no-cacheor--cache-from) need to be understood in the context of BuildKit.
Prerequisites for safe experimentation:
- A test project with a Dockerfile that has at least 4-5 instructions.
- A Docker Hub account or local registry for push/pull experiments (optional but useful for
--cache-from). - Docker 23+ or Docker Desktop latest.
Safe Configuration Path
A cache-friendly Dockerfile is the first configuration change. The golden rule: order instructions from least to most frequently changed. Base images, dependency installation, and source code copy should be separate layers.
Smallest justified change: reorder Dockerfile instructions.
Before:
FROM node:18-alpine
WORKDIR /app
COPY . .
RUN npm install
CMD ["npm", "start"]
After:
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["npm", "start"]
Why this works: COPY package*.json ./ creates a layer that changes only when package.json or package-lock.json changes. Most builds after that will reuse the RUN npm install layer, saving time.
Verify cache hit with a build:
# First build (no cache available)
docker build -t myapp:test .
# Second build without changes
docker build -t myapp:test .
On the second build, look for CACHED in the output. With BuildKit, you will see lines like:
=> [3/5] RUN npm install 0.0s
=> CACHED [4/5] COPY . . 0.0s
The CACHED marker means the layer was reused from the local cache. If you see RUN npm install re-executing and it took time, something invalidated the copy layer.
Configuration options that affect caching:
--no-cache: forces a full rebuild, ignoring cache. Useful for CI verification.--cache-from: allows specifying external cache sources, e.g., from a registry.--build-arg: build arguments become cache key components. Changing a build arg invalidates subsequent layers.--target: building a specific stage can limit cache usage to that stage and its dependencies.
Example with --cache-from:
# Pull previous image as cache source
docker pull myregistry/myapp:latest || true
# Build using registry image as cache
docker build \
--cache-from myregistry/myapp:latest \
-t myregistry/myapp:latest .
# Push for next time
docker push myregistry/myapp:latest
This pattern is widely used in CI. Note: with BuildKit, --cache-from only works if the builder supports it (the default docker driver does not support exporting cache; you need --output type=registry or the docker-container driver with cache export).
Cache mounts for package managers:
For development builds, use cache mounts to share package manager caches between builds:
# syntax=docker/dockerfile:1.4
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm \
npm install
COPY . .
The --mount=type=cache stores /root/.npm across builds, speeding up dependency resolution even when package.json changes. This is a BuildKit feature; the classic builder will error or ignore it.
Restart test for configuration:
After changing a Dockerfile, always do a clean build with no cache to ensure the image still works:
docker build --no-cache -t myapp:test .
docker run --rm -p 3000:3000 myapp:test
If the app starts and responds, the configuration is sound. Then run a cached build to confirm cache still works after the clean build.
Verification and Diagnostics
Diagnosing cache misses requires knowing what changed between builds. Because Docker uses a content-addressable store, a layer cache hit means the exact same input content and instructions were used.
Inspect image history to see layers:
docker history myapp:test
Output:
IMAGE CREATED CREATED BY SIZE COMMENT
abc123def456 2 minutes ago CMD ["npm", "start"] 0B buildkit.dockerfile.v0
<missing> 2 minutes ago COPY . . # buildkit 1.2MB buildkit.dockerfile.v0
<missing> 2 minutes ago RUN /bin/sh -c npm install # buildkit 150MB buildkit.dockerfile.v0
<missing> 2 minutes ago COPY package*.json ./ # buildkit 100kB buildkit.dockerfile.v0
<missing> 2 minutes ago WORKDIR /app 0B buildkit.dockerfile.v0
<missing> 2 minutes ago FROM node:18-alpine 150MB buildkit.dockerfile.v0
Each line is a layer. If you change a file in the source directory, the COPY . . layer will change, and all layers above it will be invalidated.
Use BuildKit progress to see cache decisions:
docker build --progress=plain -t myapp:test . 2>&1 | tee build.log
The plain progress output shows each instruction and whether it was cached. Search for CACHED or DONE vs RUNNING:
#7 [4/5] COPY . .
#7 CACHED
Find which files affected cache:
For a COPY instruction, compare file hashes between builds. You can use find with sha256sum:
find . -type f -not -path './node_modules/*' -exec sha256sum {} + | sort
Run this before and after a change to see which files differ. Any difference in the copied context changes the layer hash.
Diagnose --cache-from failures:
If using --cache-from with a registry image and the build still misses cache, check:
- The pulled image exists locally:
docker image inspect myregistry/myapp:latest - The image was built with BuildKit and has cache metadata:
docker buildx imagetools inspect myregistry/myapp:latest - The builder supports cache import: default docker driver does not; use
docker-containerdriver.
Example with Buildx and registry cache:
# Create a builder that can export cache
docker buildx create --use --name mybuilder --driver docker-container
# Build with cache export to registry
docker buildx build \
--cache-from type=registry,ref=myregistry/myapp:cache \
--cache-to type=registry,ref=myregistry/myapp:cache,mode=max \
-t myregistry/myapp:latest \
--push .
This exports cache to a separate image tag or the same image depending on configuration. The mode=max exports all intermediate layers, not just the final image layers.
Check cache disk usage and prune safely:
# Show build cache details
docker buildx du
# Prune build cache older than 24 hours
docker buildx prune --filter "until=24h"
# Prune all unused build cache
docker builder prune
These commands free space but can remove caches you intended to keep. Always use --filter to limit the window.
Failure Modes and Recovery
Even with a good Dockerfile, caching can fail silently or cause build errors. Here are common failure modes and how to recover.
1. Cache invalidation due to context changes
Symptom: Every build reruns RUN npm install even though package.json did not change.
Why: The COPY instruction that copies the entire context (COPY . .) includes files that changed, such as logs, local env files, or generated artifacts.
Diagnosis: Check build output: COPY . . is not CACHED, meaning the context hash changed. Use .dockerignore to exclude volatile files.
Recovery:
# Create .dockerignore
cat > .dockerignore << EOF
node_modules
*.log
.env
.git
EOF
Then rebuild. The context hash stabilizes, and the layer remains cached.
2. BuildKit cache mounts not working
Symptom: RUN --mount=type=cache causes build error or does not speed up builds.
Why: The Dockerfile may lack the syntax directive to enable BuildKit features, or the builder is the classic one.
Recovery:
- Add
# syntax=docker/dockerfile:1.4at the top of Dockerfile. - Ensure BuildKit is enabled:
DOCKER_BUILDKIT=1 docker build ...or Docker 23+. - If using Buildx, check builder driver:
docker buildx lsshould showdocker-containerordefaultwith BuildKit support.
3. --cache-from does not restore cache in CI
Symptom: CI builds every time from scratch despite pulling previous image.
Why: The previous image may not contain cache metadata, or the CI runner's Docker daemon does not have BuildKit enabled.
Recovery:
- In CI, enable BuildKit and Buildx.
- Use
docker/build-push-actionwithcache-from: type=registry,ref=...andcache-to: type=registry,ref=...,mode=max. - Ensure the image is pushed with cache metadata: with classic builder,
--cache-fromonly works if the image was built normally and all layers are present.
4. Layer cache grows unbounded
Symptom: Disk usage increases after many builds; docker system df shows large build cache.
Why: Every unique context or instruction creates new layers; old ones remain until pruned.
Recovery:
# Prune build cache not used in last 7 days
docker buildx prune --filter "until=168h"
# Or remove all build cache
docker builder prune -a
Schedule this in maintenance windows or CI cleanup jobs.
5. Confusion between image layers and build cache
Symptom: docker images shows images with missing layers, but build cache shows many layers.
Why: Build cache includes intermediate layers not referenced by any image. They are still useful for future builds.
Recovery: No action needed. Use docker buildx du to see cache breakdown and prune selectively.
6. Multi-stage builds and cache leaks
Symptom: Secrets or large files appear in final image despite multi-stage build.
Why: A stage that copies secrets may be cached and reused, but if the final stage copies from that stage incorrectly, secrets may leak. Also, using COPY --from=0 without limiting can bring unwanted files.
Recovery:
- Name stages explicitly:
FROM node:18 AS build - Copy only necessary artifacts:
COPY --from=build /app/dist /app - Use BuildKit secrets:
RUN --mount=type=secret,id=mysecret ...to avoid baking secrets into layers.
Operations Checklist
This checklist is for the operator who owns the build pipeline. Each item has an owner and review frequency.
| # | Task | Command / Check | Expected / Done | Owner | Review |
|---|---|---|---|---|---|
| 1 | Verify Docker and BuildKit versions | docker version, docker buildx version | Docker 23+, Buildx installed | Dev Lead | Monthly |
| 2 | Validate Dockerfile ordering | Manual review or lint with hadolint | Least-to-most changing instructions | Build Engineer | Per PR |
| 3 | Confirm .dockerignore exists and excludes volatile files | ls -la .dockerignore, review contents | Excludes node_modules, .git, logs | Build Engineer | Per PR |
| 4 | Run dry-run build with cache tracking | docker build --progress=plain | See CACHED for expected layers | CI pipeline | Every build |
| 5 | Test --no-cache build | docker build --no-cache | Build succeeds without errors | CI pipeline | Nightly |
| 6 | Test cache restore from registry | docker buildx build --cache-from type=registry,... | Laye reuse from registry | CI pipeline | Weekly |
| 7 | Monitor cache disk usage | docker system df, docker buildx du | Cache size within limits | Ops Engineer | Weekly |
| 8 | Prune old build cache | docker buildx prune --filter "until=168h" | No cache older than 7 days | Ops Engineer | Weekly |
| 9 | Document cache strategy and recovery steps | Wiki or runbook | Up-to-date runbook | Dev Lead | Quarterly |
Ownership and frequency:
- Build Engineer (or DevOps specialist) owns the Dockerfile and
.dockerignoreper pull request. They approve changes that affect layer ordering or context. - CI Pipeline (automated) owns nightly no-cache builds and weekly cache restore tests. If the pipeline fails, the on-call engineer investigates.
- Ops Engineer owns disk usage and pruning, reviewed weekly. If cache grows unexpectedly, they adjust pruning policy.
- Dev Lead reviews the overall caching strategy monthly and updates documentation quarterly or after major changes.
Recovery verification for checklist items:
After any change that could affect caching, run:
# Build twice: first populates cache, second should show CACHED
docker build -t myapp:check .
docker build -t myapp:check . | grep CACHED
If grep finds no CACHED, investigate before merging.
Common Pitfalls and How to Avoid Them
Many practitioners struggle with Docker caching due to subtle mistakes. Here are pitfalls, why they happen, and how to avoid or recover.
Pitfall 1: Copying entire context early
Mistake: COPY . . before RUN npm install or RUN pip install.
Why it happens: It feels natural to copy everything at once.
Consequence: Any file change in the project invalidates the dependency installation layer, causing full reinstall every build.
Avoidance: Split dependency files and source code:
COPY package*.json ./
RUN npm install
COPY . .
Pitfall 2: Not using .dockerignore
Mistake: The build context includes large or frequently changing files like node_modules, .git, logs, or .env.
Why it happens: Developers forget that the entire context is sent to the Docker daemon and hashed for cache.
Consequence: Build context becomes huge, cache misses occur frequently, and secrets may be exposed if .env is copied.
Avoidance: Always have a .dockerignore with at least:
.git
node_modules
*.log
.env
Test its effect with docker build --progress=plain and observe context size (the #1 [internal] load build context step shows transferred size).
Pitfall 3: Misunderstanding --cache-from
Mistake: Assuming --cache-from works the same with all builders and that any image can serve as cache.
Why it happens: The classic builder and BuildKit handle --cache-from differently. An image built without cache metadata cannot be used as cache source.
Consequence: CI builds still miss cache, leading to longer builds and wasted resources.
Avoidance: Use BuildKit and Buildx with explicit cache export:
docker buildx build \
--cache-from type=registry,ref=myregistry/myapp:cache \
--cache-to type=registry,ref=myregistry/myapp:cache,mode=max \
-t myregistry/myapp:latest \
--push .
Pitfall 4: Relying on docker builder prune without filters
Mistake: Running docker builder prune -a manually and removing caches still needed for in-progress work.
Why it happens: It looks safe, but builds in progress or scheduled soon may need those caches.
Consequence: Next builds start from scratch, slowing down development.
Avoidance: Use time-based filters and schedule pruning during off-hours:
docker buildx prune --filter "until=168h" --keep-storage 10GB
Pitfall 5: Forgetting build arguments in cache key
Mistake: Changing a build argument during build but expecting cache to work.
Why it happens: Developers think only file changes matter.
Consequence: Layers after ARG usage are invalidated, causing rebuilds.
Avoidance: Treat ARG values as part of cache key. If an argument changes frequently (like version tags), place it as late as possible in Dockerfile or use multi-stage builds to isolate it.
Pitfall 6: Not testing cache behavior in CI
Mistake: Only testing builds locally, assuming CI will cache similarly.
Why it happens: Local builds have persistent cache; CI runners may be ephemeral.
Consequence: CI builds are slow, leading to longer feedback loops.
Avoidance: Include cache restore tests in CI, use registry cache, and monitor build times.
Conclusion
Docker layer caching is not magic: it is a predictable system that rewards deliberate Dockerfile design and diligent observation. By checking versions, ordering instructions correctly, using .dockerignore, and verifying with CACHED in build output, you can cut build times dramatically.
The commands and examples in this guide give you a practical toolkit:
docker buildx duto inspect cache usage.docker build --progress=plainto see cache hits.docker buildx build --cache-fromwith registry export for CI.--mount=type=cachefor package manager caches.docker buildx prune --filterfor controlled cleanup.
Start with one low-risk verification: run a build twice on a small project and confirm the second build shows CACHED for dependency installation. Then add a .dockerignore and split your COPY instructions. Document what you changed and how it affected build time. As you gain confidence, introduce registry cache in CI and monitor disk usage with a weekly prune.
A reliable caching strategy makes failures visible, protects sensitive values, limits changes to intended resources, and defines recovery before an incident forces it. With these practices, your Docker builds will be faster, more predictable, and easier to debug.