Order Dockerfile Layers for Cache
Docker caches each instruction keyed on its inputs; the first changed instruction invalidates every layer after it. Put dependency manifests before source code so a one-line edit rebuilds one layer, not the whole dependency graph.
Procedure
- Copy only manifests first, install, then copy source:
TheCOPY package.json package-lock.json ./ RUN npm ci --omit=dev COPY . . RUN npm run buildCOPY . .invalidates the build layer on every edit; thenpm cilayer stays cached. - For Python, keep a lock with hashes and install before copying sources:
COPY requirements.txt ./thenRUN pip install --require-hashes -r requirements.txtthenCOPY . .. - Add a
.dockerignoreso an unrelated file in the context does not bust the copy layer: exclude.git,node_modules,*.log,dist,.env. - Order by change frequency, ascending: base image → system packages → language toolchain → app deps → app code → config that changes per release.
- Keep expensive-but-stable OS package installs in one
RUNwith a cleanup in the same layer:RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates && rm -rf /var/lib/apt/lists/*. - Use cache mounts for package managers to avoid download on a cache miss:
RUN --mount=type=cache,target=/root/.npm npm ci. - In CI use
docker buildx build --cache-from type=registry,ref=ghcr.io/acme/app:cache --cache-to type=registry,...so the runner reuses layers across jobs.
Pitfalls
COPY . .before the install step is the classic cache-buster; fixing only that often turns a 4-minute build into 20 seconds.apt-get updatein a layer separate fromapt-get installcaches a stale index and later installs 404 on packages.- Adding
ARG VERSIONabove the dependency install invalidates it on every version change even though deps did not move; put the ARG below. RUNwith--no-cache(buildkit flag) discards the mount cache too during debugging, making you think the Dockerfile is slow.- Mounting the source with
-v $(pwd):/appatdocker runhides whateverCOPYput there, so a cached build looks stale — that is runtime, not the cache. - A
.dockerignorethat excludes a file the install needs (e.g.patches/) makes the cached layer silently produce a wrong artifact; the build layer above it still hits cache and never rebuilds.
Verification
docker build -t app:x . && touch src/app.js && docker build -t app:x .
# second build prints: CACHED ... RUN npm ci ... <all deps>
Cold build once, edit one source file, rebuild: the dependency install line reports CACHED and total time drops by the dependency-install duration. Report the before/after layer status, not a claim that build "seems faster".