dockcheck: a Bash CLI for controlled Docker image updates

What dockcheck actually replaces

A Compose stack does not tell you when one of its images has a newer tag upstream. You find out when something breaks, or when you remember to run docker compose pull and read the output. dockcheck.sh closes that gap: it enumerates containers, asks the registry whether a newer image exists, and then either presents a numbered list for you to choose from or applies updates on its own. The README's basic example shows the interactive path, ending in a prompt that accepts ranges such as 1-2,4-5,09, a for all, or q to quit. After that it runs pull and up -d for each selected container and asks about pruning dangling images.

The audience is visible in the repository topics: bash, docker, homelab, self-hosted. This is a script you drop next to your Compose files, not a control plane. It assumes you already run Docker and Compose, either standalone or as a plugin, and that you are comfortable reading a shell script before letting it touch your stacks.

How the check and update cycle works

The script is a single Bash file, dockcheck.sh, at least Bash 4.3, with two external dependencies that do the real work. jq parses registry responses, and regclient's regctl queries registries for image metadata. The README notes that regctl requires amd64 or arm64 and links to a workaround for other architectures, which is worth reading before you assume it runs on your board.

Async checking is handled through POSIX xargs, which the README says is usually present but can be installed via the findutils package. The -x flag sets the maximum number of asynchronous subprocesses; the default is 1, and 0 disables async. The documentation states that 32 or more has been tested, so the concurrency ceiling is a knob you set rather than a fixed limit.

After a successful pull, dockcheck recreates containers. The -f flag forces stop and start of the stack after an update, with the README warning that this restarts once for every updated container within the stack. The -F flag narrows recreation to the specific container instead of the whole Compose stack, which the README describes as useful for a master-compose structure. The -R flag skips recreation entirely after pulling. These flags matter because recreation is the step that can take a service down briefly, and the script gives you several ways to control its scope.

Installing dockcheck and running a first check

The README's install instructions are deliberately minimal: download the script to a directory in your PATH, with ~/.local/ suggested. There is no package to install. If jq or regctl are missing, the README says the user is prompted to install jq with a package manager or download a static binary, and prompted to download regctl if it is not in PATH or the current working directory.

Once the script is executable, the help output is the fastest way to see every option. It prints the syntax line and an example invocation.

./dockcheck.sh -h

Before letting it pull anything, run a check-only pass. The -n flag means no updates, only checking availability. This is the safest first command because it never pulls or recreates.

./dockcheck.sh -n

You should see a progress bar, then two lists: containers on the latest version and containers with updates available, matching the format in the README's basic example.

To actually update, drop the flag and answer the prompt. Excluding containers you want to keep pinned is done with -e, and -E excludes them from applying updates while still checking whether one exists.

./dockcheck.sh -e nextcloud,heimdall

The README also documents a containerized route added in v0.8.1, with a Dockerfile and compose-example-configfile.yml and compose-example-envvars.yml at the repository root. The Dockerfile sets CONTAINERIZED_DC=true and runs supercronic against /app/crontab, so the containerized form is built around a schedule rather than a terminal session. Note the changelog entry for v0.8.2: self-updates are blocked when containerized, for both the script and the image.

Backups, exclusions and the flags that change risk

The -b flag enables image backups and takes a number of days to keep before pruning. The README states that -b ignores -p auto-prune, so backups and automatic pruning of dangling images are mutually exclusive settings. There is a separate -B flag that lists currently backed up images and exits, which is how you inspect what the backup mechanism has retained.

Labels are the other filtering mechanism. The -l flag includes only containers with a label set, and the README points to its label section for the details. Combined with -e and -E, this gives three different ways to scope an update run: by name, by label, or by the interactive selection at the prompt.

One flag deserves caution on its own. The -u flag allows automatic self updates, and the help text warns that this pulls new code and autoruns it. That is a meaningful trust decision for a script that runs unattended, and the v0.8.2 changelog shows the project has already had to block that path when containerized. If you schedule dockcheck, think about whether -u belongs in the cron line at all.

Notifications, metrics and where the edges are

Notification support is plugin-shaped rather than built in. The -i flag sends a preconfigured notification, and -N simulates updates to test notifications unconditionally, without performing checks or updates. That -N flag exists because notification configuration is easy to get wrong and hard to verify otherwise. The repository has a notify_templates directory and an addons directory, and the v0.8.0 changelog added Home Assistant event integration.

For monitoring, -c takes a directory and exports metrics as a prom file for the Prometheus node_exporter textfile collector. The -I and -M flags print custom release note URLs alongside containers with updates, requiring urls.list; -M prints them as markdown for template support.

The real limitations are structural. This is a Bash script, so every behavior depends on the shell environment it runs in, and the changelog is full of fixes around sourcing dockcheck.config, array variable handling, and restart logic, which tells you the surface area is wide. The -d flag, which only updates to images at least N days old, is documented as 2x slower, and the README notes that checks against Docker Hub are not subject to the pull limit while actual pulls are. If you run Podman, the README explicitly points to the sudo-kraken/podcheck fork rather than claiming compatibility. And if you want a daemon with a web interface and a database of update history, this is the wrong category of tool.

How it differs from Watchtower-style auto-updaters

The closest familiar alternative is an always-on container that watches other containers and updates them as new images appear. dockcheck inverts that model. It runs when you invoke it, or when cron invokes it, checks everything, and then either asks you or applies a policy you configured through flags and dockcheck.config. There is no resident process and no HTTP endpoint.

The practical difference is where the decision lives. A watcher decides for you at the moment a new image appears, which is convenient until an upstream tag moves unexpectedly. dockcheck puts the decision at the prompt, or in the flags of a scheduled run, and adds image backups via -b so a bad pull has a documented recovery path. The README's restoration section for image backups was clarified in v0.8.0, which suggests people do use it.

The trade-off runs the other way too. A watcher is always current; dockcheck is only as current as its schedule. If your cron entry runs weekly, you are a week behind by design, and the -d flag deliberately makes you later still by ignoring images younger than N days.

Editorial conclusion

dockcheck fits homelab and small self-hosted operators who run Docker Compose and want a readable, hackable update path with backups and notifications. It is the wrong tool if you want a long-running daemon with a web UI, if you run Podman (the README points to the podcheck fork), or if you are on an architecture regctl does not support without a workaround. Before adopting it, read default.config and the -h output, confirm jq and regctl are in PATH, and run ./dockcheck.sh -n once so you see the check output without any pull or recreate. Then decide whether -b image backups belong in your update routine.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. mag37/dockcheck on GitHub
3. Project website
4. README
5. Releases