Docker Layer Caching: How It Works and Optimization Tips

Intermediate·3 min read·

Fast recall

Quick revision

Core answer

Docker caches each instruction's result as a layer. A cache miss invalidates all subsequent layers. Optimize by ordering instructions from least-to-most frequently changing: COPY pom.xml first and run dependency download, then COPY src/ last. This ensures dependency layers are reused across most builds, and only source code layers rebuild on code changes.

Interview Answer3 min

Docker builds images by executing instructions one at a time and caching each resulting layer. The critical rule: Docker invalidates every layer after the first change it detects — instruction order determines whether you get a cache hit or a full rebuild.

The ordering rule — dependencies before source code

Copy and install dependencies before copying source code — COPY pom.xml . then RUN mvn dependency:go-offline, then COPY src ./src ensures a code-only change hits the cached dependency layer and skips the 3-minute download phase
Once any layer is invalidated, every subsequent layer rebuilds even if its content did not change — a source copy instruction placed before RUN mvn dependency:go-offline means every code commit triggers a full dependency re-download
For Node.js or Python: COPY package.json . then RUN npm install before COPY . . follows the same logic

`RUN` instruction consolidation

Multiple RUN instructions each create a separate layer; combining cleanup in the same RUN that installs packages keeps the image smaller — RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/* in one instruction prevents the package cache from persisting in an intermediate layer
Splitting an apt-get update from apt-get install across two RUN instructions causes the stale cache problem: Docker caches the update layer and uses the cached package list, then installs potentially outdated packages on the next build
Don't consolidate instructions that change frequently with instructions that change rarely — a RUN that sets up the OS and installs your application JAR will both re-execute on every JAR change

BuildKit and remote caching

Enable BuildKit with DOCKER_BUILDKIT=1 or use docker buildx build — BuildKit parallelizes independent build stages and provides more granular cache invalidation than the classic builder
--cache-from pulls a previous build's layers from a registry for use as cache — CI agents without a local build cache can still achieve cache hits by pulling the most recent image from the registry before building

Interview-ready guide

Interview answer

The ordering rule — dependencies before source code

Copy and install dependencies before copying source code — COPY pom.xml . then RUN mvn dependency:go-offline, then COPY src ./src ensures a code-only change hits the cached dependency layer and skips the 3-minute download phase
Once any layer is invalidated, every subsequent layer rebuilds even if its content did not change — a source copy instruction placed before RUN mvn dependency:go-offline means every code commit triggers a full dependency re-download
For Node.js or Python: COPY package.json . then RUN npm install before COPY . . follows the same logic

`RUN` instruction consolidation

Multiple RUN instructions each create a separate layer; combining cleanup in the same RUN that installs packages keeps the image smaller — RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/* in one instruction prevents the package cache from persisting in an intermediate layer
Splitting an apt-get update from apt-get install across two RUN instructions causes the stale cache problem: Docker caches the update layer and uses the cached package list, then installs potentially outdated packages on the next build
Don't consolidate instructions that change frequently with instructions that change rarely — a RUN that sets up the OS and installs your application JAR will both re-execute on every JAR change

BuildKit and remote caching

Enable BuildKit with DOCKER_BUILDKIT=1 or use docker buildx build — BuildKit parallelizes independent build stages and provides more granular cache invalidation than the classic builder
--cache-from pulls a previous build's layers from a registry for use as cache — CI agents without a local build cache can still achieve cache hits by pulling the most recent image from the registry before building

03 · Deep dive