Skip to main content

imagenudge-lite: Docker image update checker for running containers, read-only

imagenudge-lite helps with a Docker image update checker for a quick "which of my containers are behind?" check on one Docker host: it lists the running containers through the local Docker socket, asks the registry whether each container's tag now points to a different image digest, and whether a newer version tag exists (for example 1.25.1 -> 1.26.0). It prints a plain-text list and exits 1 when something can be updated, so it fits a cron job. It never pulls, restarts or edits anything. One file, Python 3.9+ standard library only, MIT.

Need compose-file scanning, webhook / ntfy / SMTP email alerts, or JSON output? That is the full ImageNudge (one-time payment, yours to keep, no subscription). A table later in this README lists what lite does and what the paid tool adds. Or get every PyForge tool, current and future, with the All-Access Pass ($99, one payment).

  • Optional pip install, or just download the one file. No config, no state, no agent to run.
  • Only GET requests to the Docker socket (/containers/json, /images/<id>/json). Registry checks are HEAD on the manifest plus the tag list; no image layers are downloaded.
  • Public images only, anonymous access (Docker Hub, and registries that hand out anonymous pull tokens, e.g. public ghcr.io and quay.io images). No credentials are read or sent.
  • Flags: --socket, --no-tags, --demo, --timeout, --version. After pip install, use imagenudge-lite in place of python3 imagenudge_lite.py.

Install

pip install imagenudge-lite
imagenudge-lite --help

Or download the single file (Python 3.9+, stdlib only, no extra packages):

curl -fsSLO https://raw.githubusercontent.com/alessio1999xx-debug/imagenudge-lite/main/imagenudge_lite.py
python3 imagenudge_lite.py --help

See the output first (offline demo)

python3 imagenudge_lite.py --demo
# imagenudge-lite 0.1.0: demo (sample data, no Docker, no network)
#
#   UPDATE  gitea        gitea/gitea:1.21.0  newer tag 1.21.3
#   UPDATE  redis-cache  redis:7.2-alpine    new digest for :7.2-alpine (b2b2b2b2b2b2 -> d4d4d4d4d4d4); newer tag 7.4-alpine
#   OK      traefik      traefik:v2.10.4     digest matches :v2.10.4
#   SKIP    my-app       my-app:dev          no registry digest locally (built or loaded locally?)
#
# 4 container(s): 2 update(s) available, 1 up to date, 1 skipped, 0 could not be checked.
# Nothing was pulled or restarted. Review the changelog, then update when you choose.

Check running Docker containers for newer images

python3 imagenudge_lite.py
# needs read access to /var/run/docker.sock (root, or a user in the docker group)

python3 imagenudge_lite.py --socket /run/user/1000/docker.sock   # rootless Docker
python3 imagenudge_lite.py --no-tags                             # digests only, skip the tag list

If DOCKER_HOST is set to a unix:// path it is used as the default socket. TCP / SSH Docker hosts are not supported by the lite version.

How a Docker image update is detected

Status Meaning
UPDATE The registry digest for the tag the container runs differs from the local image's digest (e.g. :latest or :7.2-alpine was rebuilt upstream), and/or a newer version tag exists
OK Digest matches and no newer version tag was found
SKIP Nothing to compare: container started from an image ID, pinned by digest only, or an image built/loaded locally with no registry digest
ERROR The registry could not be checked (private or missing image, rate limit, no network). Shown with the reason

Newer tags keep the same style and suffix as the tag you run: 1.25.1 is compared with X.Y.Z tags, 16-alpine with N-alpine, v2.10.4 with vX.Y.Z. Tags like latest or stable only get the digest check. The lite version reads up to 3 pages (3,000 tags) of the tag list, so on repositories with huge tag lists the "newer tag" suggestion can be lower than the real newest one. Multi-arch images are compared by their index digest, which is what docker pull by tag records locally.

Exit codes for cron

Exit code Meaning
0 Every image that could be checked is up to date (or no running containers)
1 At least one container has an update available
2 Docker socket not reachable, bad arguments, or no image could be checked at all
# crontab: check every morning at 07:00, keep the last report
0 7 * * * python3 /opt/imagenudge_lite.py > /var/log/imagenudge-lite.txt 2>&1

Scheduling is up to you (cron, a systemd timer). The lite version does not send any alerts.

imagenudge-lite vs ImageNudge

imagenudge-lite checks the running containers on one local Docker socket and prints a plain-text list. That's it.

The full ImageNudge adds compose-file scanning, webhook / ntfy-style and SMTP email alerts, JSON output and a printed list of the docker pull commands to run yourself. One-time payment, yours to keep. No subscription.

Lite is not a strict subset: its 0 / 1 / 2 exit codes for cron are not in the paid tool.

Capability Lite (free) Paid ImageNudge
Running containers via the local Docker socket Yes Yes
docker-compose.yml files (--compose-file, several at once) No Yes
New digest for the same tag Yes Yes
Newer semver tag (same suffix and style) Yes (up to 3 tag-list pages) Yes (up to 5 tag-list pages)
Registries Public images, anonymous access Public images, anonymous access
Alerts No Webhook / ntfy-compatible POST (--notify-url) and SMTP email (--email-to)
Output Plain text list Text or JSON (--format json)
Prints the docker pull commands to run (--apply, never runs them) No Yes
Exit code 1 when updates are available Yes No (exits 0)
Offline --demo Yes Yes, plus a built-in --self-test

Neither version pulls images, restarts containers, edits files, or reads registry credentials.

Or get every PyForge tool, current and future, with the All-Access Pass ($99, one payment).

Tests

python3 test_imagenudge_lite.py

The tests are offline: a fake registry, and a tiny fake Docker API on a temporary unix socket. No Docker and no network needed.

License

MIT (this lite version). The full ImageNudge is sold separately under its own license.

Metadata

Release files for imagenudge-lite 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for imagenudge-lite 0.1.0
File Size Uploaded Provenance Actions
imagenudge_lite-0.1.0.tar.gz 15.1 kB With provenance Details for imagenudge_lite-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for imagenudge-lite 0.1.0
File Interpreter ABI Platform Actions
imagenudge_lite-0.1.0-py3-none-any.whl Python 3 none any Details for imagenudge_lite-0.1.0-py3-none-any.whl

Total release size: 26.8 kB

Release files / imagenudge_lite-0.1.0.tar.gz

Download URL imagenudge_lite-0.1.0.tar.gz
Size 15.1 kB
Tags Source
SHA-256 checksum
How to use checksums
540ec7f6c9c9229f6e1bf5b34db01b9a1cc0464f2f09af3e70cd59e9d486acd5
BLAKE2b-256 checksum
How to use checksums
5ef28d167cadc2f7337e64e282f54fa4ed72c4d0fc0878372794a0646db0b95b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / imagenudge_lite-0.1.0-py3-none-any.whl

Download URL imagenudge_lite-0.1.0-py3-none-any.whl
Size 11.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
da8aceba17e7c5bf41ebd1e7950e94388746e942b9d7603489c2a7699e33d8e2
BLAKE2b-256 checksum
How to use checksums
782016fbcea857a1abfe333cfe0b807eb000cb216fd2657a04bb942bf42272cd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for imagenudge-lite 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for imagenudge_lite-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page