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
GETrequests to the Docker socket (/containers/json,/images/<id>/json). Registry checks areHEADon 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.ioandquay.ioimages). No credentials are read or sent. - Flags:
--socket,--no-tags,--demo,--timeout,--version. Afterpip install, useimagenudge-litein place ofpython3 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.