docker-check-updates

docker-check-updates (dcu)

Find and apply newer Docker image tags in Dockerfiles and Compose files, with ergonomics inspired by npm-check-updates.

Node.js (TypeScript), zero runtime dependencies.

Install

npm install --save-dev docker-check-updates
npx dcu --help

Or without installing:

npx docker-check-updates --help

Quick start

# Report available upgrades (default target: latest)
dcu

# Same, but only bump the trailing version digit if that tag exists
dcu -t next

# Write changes
dcu -u
dcu -t next -u

# Limit scope
dcu -f alpine,mariadb
dcu --packageFile '.docker/*Dockerfile,docker-compose.yml'

Targets

Target	Behaviour
latest	Newest tag with the same suffix (e.g. stays on -noble, -apache-trixie)
minor	Newest with the same major
patch	Newest with the same major.minor
next	Increment trailing digits once (3.24 → 3.25) if that exact tag exists

Floating tags (latest, lts, edge, …) are never auto-bumped as pins.

What is scanned

• Dockerfiles / *.Dockerfile / Containerfile: FROM image:tag, including FROM image:${ARG} when ARG NAME=versioned-tag is declared above
• Compose files (compose*.yml, docker-compose*.yml): image: name:tag

By default the tool walks the working tree (skips node_modules, vendor, .git, dist).

CLI

dcu [options]

  -u, --upgrade              Write upgrades to disk
  -t, --target <target>      latest | minor | patch | next
      --cwd <dir>            Working directory
  -f, --filter <list>        Only these images (comma-separated, * wildcards)
  -x, --reject <list>        Ignore these images
      --packageFile <paths>  Explicit files/globs
  -c, --config <file>        Config path (default: dcu.config.json)
      --json                 Machine-readable output
      --strict-digest        Exit 1 on referenceTag digest mismatch (default)
      --no-strict-digest
  -h, --help
  -v, --version

Config file

Optional dcu.config.json (see dcu.config.example.json):

{
  "target": "next",
  "files": [".docker/*Dockerfile", "docker-compose.yml"],
  "packageRules": [
    {
      "matchImages": ["mariadb"],
      "referenceTag": "lts"
    },
    {
      "matchImages": ["php"],
      "matchArgs": ["PHP_IMAGE_TAG"],
      "referenceTag": "apache"
    }
  ],
  "sync": [
    {
      "image": "mariadb",
      "from": "docker-compose.yml",
      "to": ["docker-compose.fpm.yml", ".docker/sql.Dockerfile"]
    },
    {
      "image": "alpine",
      "from": ".docker/fpm.Dockerfile",
      "to": [".docker/nginx.Dockerfile"]
    }
  ],
  "githubReleases": [
    {
      "owner": "mlocati",
      "repo": "docker-php-extension-installer",
      "files": [
        {
          "path": ".docker/dev.Dockerfile",
          "line": "ARG DOCKER_PHP_EXTENSION_INSTALLER_VERSION={version}"
        }
      ]
    }
  ]
}

packageRules

• matchImages / matchFiles / matchArgs — select pins
• referenceTag — after resolve, compare digests of the pin tag vs this floating tag (Docker Hub multi-arch digest)
• target — per-rule override

sync

Copy an image tag from a source file to one or more targets (after upgrades when using -u). Source and targets may be Compose files (image: name:tag) or Dockerfiles (FROM name:tag).

githubReleases

Bump non-image version pins from GitHub Releases latest tag. Template lines use {version} (semver without a forced v prefix). Set GITHUB_TOKEN or GH_TOKEN if you hit API rate limits.

Parity with a typical “bump Docker deps” script

Feature	Support
Bump FROM tags	yes
Bump Compose image: tags	yes
Dockerfile ARG image tags (FROM php:${TAG})	yes
Single-step trailing bump	-t next
Jump to newest matching release	-t latest (default)
Digest equals lts / latest / …	packageRules.referenceTag
Sync tags across Compose / Dockerfiles	sync
GitHub release pins (e.g. install scripts)	githubReleases
Filter / reject	-f / -x
JSON output	--json

Library API

import { run } from "docker-check-updates";

const result = await run({
  cwd: process.cwd(),
  target: "next",
  upgrade: false,
  json: false,
  filter: [],
  reject: [],
  files: [],
  packageRules: [{ matchImages: ["mariadb"], referenceTag: "lts" }],
  sync: [],
  githubReleases: [],
  strictDigest: true,
});

Development

npm install
npm run build
npm test

Notes

• Registry access is Docker Hub’s HTTP API (no pulls). Official images use the library/ namespace automatically.
• Tag listing is paginated and filtered; unusual tagging schemes may need -t next or tighter filters.
• This tool updates repo pins. It does not rebuild or redeploy running containers.
• Limits / room to grow: image resolution is Docker Hub–only (no GHCR/ECR/private registries or auth); discovery is Compose + Dockerfile (not K8s, Helm, or CI image: fields), with simple globs; digests use the Hub multi-arch API (no pull verification or tag@sha256 pinning); next bumps one step per run; non-image pins are GitHub Releases with exact line templates; apply is text replace (first match for images). Natural extensions: OCI registries, richer scanners, digest write mode, and CI-friendly exit codes when upgrades exist.