How do Docker image layers and build caching work?

Question

Accepted Answer

Docker images are built in **layers** — each Dockerfile instruction creates a layer, and Docker **caches** layers to speed up rebuilds. Understanding layers and caching is key to writing efficient Dockerfiles that build fast and produce smaller images.

## Layers — each instruction adds a layer

```text
Each Dockerfile instruction (FROM, RUN, COPY, etc.) creates a read-only LAYER:
  → layers stack to form the image; layers are CACHED and SHARED between images
  → if a layer is unchanged, Docker REUSES the cached layer (skips rebuilding it)
→ Layer caching makes rebuilds fast — only changed layers (and those AFTER) rebuild.
```

## The caching rule (order matters)

```text
Docker caches layers IN ORDER. When an instruction's input changes, that layer AND
ALL layers AFTER IT are rebuilt (cache invalidated from that point down).
→ Put STABLE things EARLY and FREQUENTLY-CHANGING things LATE in the Dockerfile.
```

## The classic optimization: dependencies before code

```dockerfile
# ✅ GOOD — copy dependency manifest first, install, THEN copy code
COPY package*.json ./
RUN npm install          # this layer is cached UNLESS package.json changes
COPY . .                 # code changes here don't invalidate the npm install layer

# ❌ BAD — copy everything first
COPY . .                 # ANY code change invalidates...
RUN npm install          # ...so npm install RE-RUNS on every code change (slow!)
```

By copying dependency files and installing **before** copying the rest of the code, the (slow) dependency-install layer stays cached across code changes — a hugely important optimization that makes rebuilds fast.

## Reducing image size

```text
✓ Combine related RUN commands (fewer layers) and clean up in the SAME layer
  RUN apt-get update && apt-get install -y x && rm -rf /var/lib/apt/lists/*
✓ Use small base images (alpine, slim, distroless)
✓ Use .dockerignore to exclude unneeded files from the build context
✓ Use multi-stage builds (build artifacts in one stage, copy only what's needed)
```

## Why it matters

Understanding Docker layers and build caching is important for **writing efficient Dockerfiles** that build quickly and produce smaller images, so it's valuable practical knowledge that significantly affects developer productivity and deployment.

The foundational concept — each Dockerfile instruction creates a cached, reusable **layer**, and Docker **reuses unchanged cached layers** while rebuilding changed layers and everything after them — explains how to make builds fast.

The **critical caching rule** (cache invalidates from the first changed instruction downward, so order matters: stable things early, frequently-changing things late) drives the **single most important optimization**: copying dependency files and installing dependencies **before** copying application code, so the slow dependency-install layer stays cached across the frequent code changes (rather than re-running `npm install`/`pip install` on every code change — a difference between fast and painfully slow rebuilds).

Understanding this pattern alone dramatically improves build times, a constant developer-experience concern.

Knowing techniques to **reduce image size** — combining RUN commands with cleanup in the same layer, using small base images (alpine, slim, distroless), `.dockerignore` to exclude unneeded files, and multi-stage builds — produces smaller, faster-to-deploy images (reducing storage, transfer time, and attack surface).

Since Docker builds happen constantly (in development and CI/CD) and slow builds or bloated images hurt productivity and deployment, and since understanding layers and caching is what enables writing Dockerfiles that build fast and stay small, understanding Docker layers and build caching — the layer model, the order-dependent caching rule, the dependencies-before-code optimization, and size-reduction techniques — is valuable, frequently-applied knowledge for efficient Docker use, a key skill distinguishing those who write fast, lean Dockerfiles from those who suffer slow builds and bloated images.