How to pin base image versions in Docker?

· Category: Docker

Short answer

Pin base image versions by using specific tags like node:18.17.1-alpine instead of latest. For maximum reproducibility, pin the image digest with @sha256:....

Steps

  1. Avoid latest tags in production.
  2. Use semantic version tags for base images.
  3. Pin to a digest for immutable references.
  4. Update pinned versions deliberately after testing.

Example

# Good: specific version
FROM node:18.17.1-alpine

# Better: immutable digest
FROM node:18.17.1-alpine@sha256:abc123...

Tips

  • Use Renovate or Dependabot to automate base image update PRs.
  • Document the rationale for chosen base image versions.
  • Test thoroughly when upgrading base images, as they may include OS-level changes.

Common issues

  • latest can silently pull a new OS version, breaking compatibility.
  • Digest pinning prevents security patches from being applied automatically.
  • Some registries prune old tags, making digests the only reliable reference.