combine-apt-update-install

apt-get update and install in separate Docker RUN layers cause stale package caches and 404 errors. Why they must share one RUN.

On this page

RUN apt-get update on its own line looks harmless, but Docker caches it as a layer. On a later build, that cached — now weeks-old — package index is reused while apt-get install runs fresh, and it either installs outdated packages or fails with 404 Not Found because the index points at package versions the mirror no longer serves. This rule flags apt-get update and apt-get install living in separate RUN instructions.

What the rule catches

Dockerfile — update layer goes stale in cache

FROM debian:12-slim
RUN apt-get update
RUN apt-get install -y curl

Scanning this file reports:

⚠ WARN [docker-doctor/combine-apt-update-install]
  RUN apt-get update used without apt-get install in the same instruction. This can cause caching issues and build failures.

Why it matters

The two commands are only correct as a unit: the update fetches the index, the install consumes it. Split across layers, Docker's cache can (and will) reuse one without the other — the classic "cached apt update" trap that makes builds fail mysteriously only on machines with an old build cache. Combining them in one RUN means the index is always exactly as fresh as the install that uses it, and lets you clean the index in the same layer so it never ships in the image.

How to fix it

Combine apt-get update and apt-get install in the same RUN instruction (e.g. RUN apt-get update && apt-get install -y --no-install-recommends <package> && rm -rf /var/lib/apt/lists/*).

Dockerfile — index fetched, used, and removed in one layer

FROM debian:12-slim
RUN apt-get update \
  && apt-get install -y --no-install-recommends curl \
  && rm -rf /var/lib/apt/lists/*

--no-install-recommends skips the recommended-package tree that quietly doubles install size, and the trailing rm -rf /var/lib/apt/lists/* removes the package index from the image — covered in depth by clean-package-cache. All three habits belong in the same RUN.

Rule details

Rule key — docker-doctor/combine-apt-update-install
Category — Best Practices
Default severity — warning
Applies to — Dockerfiles

Explain this rule from the CLI:

npx @docker-doctor/cli@latest rules explain docker-doctor/combine-apt-update-install

Change its severity — or turn it off — in your config file:

// docker-doctor.config.ts
export default {
  rules: {
    "docker-doctor/combine-apt-update-install": "off",
  },
};

Severity affects the health score: error findings cost more points than warning, and info costs the least.