# Docker Layer Caching Explained: Faster Image Builds in CI

> Docker builds images in cached layers, reusing unchanged ones to skip work. Learn how layer caching works and how to order a Dockerfile for hits.

Source: https://latchkey.dev/learn/ci-cd-concepts/docker-layer-caching-explained  
Updated: 2026-06-25

Docker builds an image as a stack of cached layers. Order your Dockerfile so the parts that rarely change come first, and most builds reuse almost everything.

Each instruction in a Dockerfile produces a layer. Docker can reuse a layer from a previous build if its inputs are unchanged - but a single early change invalidates everything after it. Ordering is everything.

## How layers are cached

Docker hashes each instruction and its inputs. If the hash matches a cached layer, it reuses it instead of re-running the step. The moment one layer’s inputs change, that layer and every layer below it are rebuilt - the cache is invalidated downward, not selectively.

## Order for cache hits

Put stable instructions first and volatile ones last. Copy your dependency manifest and install dependencies *before* copying your application source, so a code change does not bust the dependency-install layer.

```Cache-friendly ordering
COPY package*.json ./
RUN npm ci          # cached unless deps change
COPY . .            # changes often; only this layer rebuilds
RUN npm run build
```

## Why CI often misses the cache

- Ephemeral runners start with no local image cache each run.
- No external cache backend configured, so nothing is restored.
- Copying source before installing deps, invalidating deps every commit.
- A changing build argument near the top of the file busting everything.

## Caching across CI runs

Because ephemeral runners have no local cache, you need an external one: BuildKit’s registry-backed cache (`--cache-from` / `--cache-to`) stores layers in a registry so the next run restores them. Without that, every CI build is effectively a cold build.

## FAQ

### What is Docker layer caching Explained: faster image builds in CI?

Each instruction in a Dockerfile produces a layer. Docker can reuse a layer from a previous build if its inputs are unchanged - but a single early change invalidates everything after it. Ordering is everything.

### How layers are cached?

Docker hashes each instruction and its inputs. If the hash matches a cached layer, it reuses it instead of re-running the step. The moment one layer’s inputs change, that layer and every layer below it are rebuilt - the cache is invalidated downward, not selectively.

### Order for cache hits?

Put stable instructions first and volatile ones last. Copy your dependency manifest and install dependencies *before* copying your application source, so a code change does not bust the dependency-install layer.

### Caching across CI runs?

Because ephemeral runners have no local cache, you need an external one: BuildKit’s registry-backed cache (--cache-from / --cache-to) stores layers in a registry so the next run restores them. Without that, every CI build is effectively a cold build.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt