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"]
    }
  ],
  "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 one Compose file to others (after upgrades when using -u).

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 files | 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.