docker-devtools

Work on the Docker files in a repository: the build context a Dockerfile would send, and the image references it and your Compose files point at.

$ docker-devtools image ls
Dockerfile:1        python:3.11-slim
compose.yaml:3      nginx:1.25-alpine

$ docker-devtools image update --tag-policy same-pattern --dry-run
Dockerfile:1     python:3.11-slim -> python:3.14-slim      (tag 3.11-slim -> 3.14-slim)
compose.yaml:3   nginx:1.25-alpine -> nginx:1.31-alpine    (tag 1.25-alpine -> 1.31-alpine)

Why another one

Renovate and Dependabot already update image references, and they do it well. They run as bots against a repository and open pull requests. This one runs on your machine and edits the files in place. It is fast enough for a pre-commit hook, so a stale base image gets caught before it is ever committed.

Where the semantics are Docker's, this defers to Docker's own code:

Step Package
Parse Dockerfiles moby/buildkit/frontend/dockerfile/parser and instructions
Parse image references google/go-containerregistry/pkg/name
Talk to registries google/go-containerregistry/pkg/v1/remote
Match .dockerignore rules moby/patternmatcher
Walk a build context tonistiigi/fsutil, the package BuildKit sends contexts with

None of the .dockerignore semantics are reimplemented here, and CI checks that rather than asserting it: for every fixture, scripts/conformance.sh builds FROM scratch with COPY . /, exports the image as a tarball, and diffs the tar members against what context ls reports.

Install

$ uvx docker-devtools image ls          # no install
$ pipx run docker-devtools image ls     # no install
$ uv tool install docker-devtools
$ pip install docker-devtools
$ mise use ubi:FlavioAmurrioCS/docker-devtools

Prebuilt binaries are attached to each release. With a Go toolchain:

$ go install github.com/FlavioAmurrioCS/docker-devtools/cmd/docker-devtools@latest

Reading and updating files doesn't require a Docker installation or a running daemon. Registry lookups authenticate with the same ~/.docker/config.json the docker CLI uses.

Usage

docker-devtools context ls [PATH]        list the files Docker would send
docker-devtools context explain PATH     show which .dockerignore rule decided a path
docker-devtools image ls [PATH...]       list every image reference, with file and line
docker-devtools image update [PATH...]   rewrite references in place
docker-devtools install-docker-plugin    register as "docker devtools"

Updating image references

What changes is split by how much judgement it needs.

--pin-digest resolves the current tag to a digest and appends it, turning nginx:1.29 into nginx:1.29@sha256:…. It doesn't decide anything about versions, so it is reversible and safe to run anywhere.

--tag-policy moves the tag. The default, same-pattern, moves only the last component and keeps the suffix, so how specific your tag is decides how far it may move:

Current tag same-pattern minor patch latest
3.12-slim 3.13-slim 3.13-slim no change 4.0-slim
3.12.1-slim 3.12.7-slim 3.13.0-slim 3.12.7-slim 4.0-slim
latest no change no change no change no change

No policy ever changes the suffix: -alpine and -slim are different images, and swapping them would change your base distribution without saying so. Tags with no version, such as latest or bookworm, are never moved, because there is no ordering to move along.

Add --dry-run to see the plan without writing, and --fail-on-diff to exit non-zero when anything would change, which is what makes it useful in CI.

What it will not touch

Some references cannot be resolved to an image, and those are reported rather than guessed at. Pass --unresolved to image ls to see them:

  • FROM builder, where builder is an earlier stage
  • COPY --from=0, which indexes a stage
  • FROM $BASE, which depends on a build argument
  • FROM scratch, which is the empty base rather than a registry image
  • Compose values built from variables, such as ${REGISTRY}/app:latest

Editing in place

An update splices the new reference into the exact byte range the parser reported. It never re-encodes the file, so comments, quoting style, anchors and whitespace all survive:

    image: "nginx:1.29-alpine"   # keep this comment and the quotes

becomes

    image: "nginx:1.31-alpine"   # keep this comment and the quotes

If a byte range no longer holds the text the parse said it held, the update fails instead of writing. A rewrite that has drifted from the parse is a bug, and corrupting the file would hide it.

Shell completion

The binary emits a usage spec describing its own command tree, and the usage CLI turns that into completions for bash, zsh, fish, powershell and nushell:

$ mise use usage
$ usage g completion zsh docker-devtools --usage-cmd 'docker-devtools --usage-spec' --install

The generated scripts call back to usage at completion time, so it has to stay on your PATH. mise run completions regenerates all five, plus a markdown reference, into build/.

As a Docker CLI plugin

$ docker-devtools install-docker-plugin
$ docker devtools image ls

This symlinks the binary into ~/.docker/cli-plugins/. Use --system to install it for every user.

The subcommand is devtools because Docker validates plugin names against ^[a-z][a-z0-9]*$ and refuses to load anything else. Python wheels cannot do this step at install time: they have no post-install hook, and ~/.docker/cli-plugins/ sits outside every Python install path.

Python API

The wheel bundles the binary and a typed wrapper.

from docker_devtools import image_ls
from docker_devtools import image_update

for ref in image_ls(".").resolved():
    print(f"{ref.path}:{ref.line}", ref.repository, ref.tag)

report = image_update(".", pin_digest=True, dry_run=True)
for change in report.changes:
    print(change.old, "->", change.new, f"({change.reason})")

image_update defaults to dry_run=True, so calling it by accident cannot rewrite a repository.

Development

mise.toml defines the tools and the tasks.

$ mise run build         # compile into ./build
$ mise run test          # go test + pytest
$ mise run lint          # pre-commit across the repo
$ mise run conformance   # diff context listing against real docker build
$ mise run completions   # regenerate completions and docs
$ mise run wheels        # every platform wheel into ./dist
$ mise run test-clone    # verify a fresh clone in a container

Registry behaviour is tested against go-containerregistry's in-process registry, so the suite doesn't touch the network or carry recorded fixtures.

License

MIT. See LICENSE.

src/docker_devtools/_find.py adapts the binary-discovery search order from uv, which is MIT OR Apache-2.0.

Project links

Data verified by PyPI on Aug 30, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.1.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for FlavioAmurrioCS from gravatar.com FlavioAmurrioCS

Credits

Author: Flavio Amurrio

GitHub Statistics

Data verified by PyPI on Aug 30, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Tags

build-context buildkit docker docker-compose dockerfile dockerignore pre-commit

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

docker_devtools-0.0.1.tar.gz (44.7 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

docker_devtools-0.0.1-py3-none-win_arm64.whl (4.4 MB view details)

Uploaded Python 3Windows ARM64

docker_devtools-0.0.1-py3-none-win_amd64.whl (5.0 MB view details)

Uploaded Python 3Windows x86-64

docker_devtools-0.0.1-py3-none-musllinux_1_2_x86_64.whl (4.8 MB view details)

Uploaded Python 3musllinux: musl 1.2+ x86-64

docker_devtools-0.0.1-py3-none-musllinux_1_2_aarch64.whl (4.3 MB view details)

Uploaded Python 3musllinux: musl 1.2+ ARM64

docker_devtools-0.0.1-py3-none-manylinux_2_17_x86_64.whl (4.8 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

docker_devtools-0.0.1-py3-none-manylinux_2_17_aarch64.whl (4.3 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

docker_devtools-0.0.1-py3-none-macosx_11_0_arm64.whl (4.5 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

docker_devtools-0.0.1-py3-none-macosx_10_9_x86_64.whl (4.9 MB view details)

Uploaded Python 3macOS 10.9+ x86-64

File details

Details for the file docker_devtools-0.0.1.tar.gz.

File metadata

  • Download URL: docker_devtools-0.0.1.tar.gz
  • Upload date:
  • Size: 44.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for docker_devtools-0.0.1.tar.gz
Algorithm Hash digest
SHA256 03d853c8a5f6ada0d661378b6f68cc7992b1b2a6664967aa4073d45392371f1d
MD5 6f1347bcf9903c86a71a16cd445601f3
BLAKE2b-256 b795ce9251f0883758d0b6373c44c47f5de485da4c43c6d4ad5f760d730189d6

See more details on using hashes here.

Provenance

The following attestation bundles were made for docker_devtools-0.0.1.tar.gz:

Publisher: main.yaml on FlavioAmurrioCS/docker-devtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file docker_devtools-0.0.1-py3-none-win_arm64.whl.

File metadata

File hashes

Hashes for docker_devtools-0.0.1-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 92bd2b4f970f199f1b2841a68be0a21026f9ec1707529ba3fdc01cb427a8eb01
MD5 f79a2a1f5eb94adc2155118eb6e37a30
BLAKE2b-256 19d3fe457e932479c43dbf54eab5f1875a76c2f3a8d47416965e58217ca95748

See more details on using hashes here.

Provenance

The following attestation bundles were made for docker_devtools-0.0.1-py3-none-win_arm64.whl:

Publisher: main.yaml on FlavioAmurrioCS/docker-devtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file docker_devtools-0.0.1-py3-none-win_amd64.whl.

File metadata

File hashes

Hashes for docker_devtools-0.0.1-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 e49e437cc5e60a2c2e5af1bc5de0555d8e6e235d79d5d48c0817a6ea9fb2b817
MD5 bcc69d2363007eb315d32cf2664d9182
BLAKE2b-256 7c4b8ab2c5a05c3565355a19123c1619388a0cd8246179cbb9197f87db6644f4

See more details on using hashes here.

Provenance

The following attestation bundles were made for docker_devtools-0.0.1-py3-none-win_amd64.whl:

Publisher: main.yaml on FlavioAmurrioCS/docker-devtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file docker_devtools-0.0.1-py3-none-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for docker_devtools-0.0.1-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 ed9e7b2a69544a6c6d599bb5ebcb6b590b5e86e85de5e265fcacba5af47e9bea
MD5 93e0b9edcd5f68c3431bfdf44527370b
BLAKE2b-256 e356167626ba0914dac814af17b568148d1c6b126052686c992240d2e0091ece

See more details on using hashes here.

Provenance

The following attestation bundles were made for docker_devtools-0.0.1-py3-none-musllinux_1_2_x86_64.whl:

Publisher: main.yaml on FlavioAmurrioCS/docker-devtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file docker_devtools-0.0.1-py3-none-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for docker_devtools-0.0.1-py3-none-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 efadf5500ba9f132537a60a71b9ddc1c17b415484e306bd812d21d80f4b10792
MD5 e47536327e8a6b90754a682caae542a3
BLAKE2b-256 40857e16c5ade51162c2ab644dcb33bbb6f9325708b8fc6d7f8a72b9413bd159

See more details on using hashes here.

Provenance

The following attestation bundles were made for docker_devtools-0.0.1-py3-none-musllinux_1_2_aarch64.whl:

Publisher: main.yaml on FlavioAmurrioCS/docker-devtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file docker_devtools-0.0.1-py3-none-manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for docker_devtools-0.0.1-py3-none-manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 a718299bdb102c898b8b60527b0c9925aadc8e83eb8adc4c22a630016b974ed2
MD5 9a20a1215f280faa474b7d5a372a3835
BLAKE2b-256 540eff0541a66d22a4b70bf9ea33e4a9151e7027ce73c9cd311a0a3a8cada458

See more details on using hashes here.

Provenance

The following attestation bundles were made for docker_devtools-0.0.1-py3-none-manylinux_2_17_x86_64.whl:

Publisher: main.yaml on FlavioAmurrioCS/docker-devtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file docker_devtools-0.0.1-py3-none-manylinux_2_17_aarch64.whl.

File metadata

File hashes

Hashes for docker_devtools-0.0.1-py3-none-manylinux_2_17_aarch64.whl
Algorithm Hash digest
SHA256 6dc83834b0b0a16ef90dc4e89f414f895067db1703a3641d349dab0ff9e550f0
MD5 3b577b722b01b2b59dc547d2a506e8d1
BLAKE2b-256 94477f7fcd9cbf82a6d0712a1b8e7128f3a1e268929cd4a33f5a681ea7b3bffa

See more details on using hashes here.

Provenance

The following attestation bundles were made for docker_devtools-0.0.1-py3-none-manylinux_2_17_aarch64.whl:

Publisher: main.yaml on FlavioAmurrioCS/docker-devtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file docker_devtools-0.0.1-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for docker_devtools-0.0.1-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 29ac67b07b9c24b8f15c1d58ca1617a02ac97f63e8a7e78a847be9f4681f0a4f
MD5 6ebb8f4beccfe0745de40b084c762576
BLAKE2b-256 92aca68d9ff816d58543d47d776b8c962f65dac69d6b290cf9fad2fe74f1f722

See more details on using hashes here.

Provenance

The following attestation bundles were made for docker_devtools-0.0.1-py3-none-macosx_11_0_arm64.whl:

Publisher: main.yaml on FlavioAmurrioCS/docker-devtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file docker_devtools-0.0.1-py3-none-macosx_10_9_x86_64.whl.

File metadata

File hashes

Hashes for docker_devtools-0.0.1-py3-none-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 8371443d57f691f4de2337db6c525ab1ba78598f2df59787c8564c784e978f87
MD5 07725b76f2b3f4fa4d90384d46609715
BLAKE2b-256 bec3939dfff215ea6c996a160d8d894e710faf1b79493ccd2d8432476269799f

See more details on using hashes here.

Provenance

The following attestation bundles were made for docker_devtools-0.0.1-py3-none-macosx_10_9_x86_64.whl:

Publisher: main.yaml on FlavioAmurrioCS/docker-devtools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.1.0

9 files

This release

0.0.1 This release

9 files

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