Docker Update

A command line utility for keeping your Docker and OCI images up to date.

Works with:

• Dockerfiles
• docker-compose.yaml
• Kubernetes Manifests (Pods, Deployments, Jobs, etc.)

Quickstart

Update your images where ever they live:

docker-update Dockerfile docker-compose.yaml path/to/job.yaml

Apply your updates to your running containers:

docker-compose up -f docker-compose.yaml -d
kubectl apply -f path/to/job.yaml

Add the --dry-run flag to preview the prospective updates without modifying any files.

Use the --list flag to see the current list of images in the given files.

Tag Update Policies

By default docker-upgrade will not change the tags in your image declarations. It will just pin the image digest for the latest available version of that tag. You can request docker-upgrade to update your tags by adding either a special custom property, annotation, or comment depending on the format you are working with.

The spec for the policy declarations follows the conventions of the Python versioning system PEP 440 with one extension. You can add a regex requirement to help match the variant of the tag you want. Using >=3, /slim/ will match tags with a version of 3 or greater and contain the string "slim".

Docker image tags do not follow the semver convention exactly, so the semver portions of the requirement will match the first semver-like number in the tag. Use the regex patterns to try to match the rest. All tags matching the policy are sorted first by their match semver component, then lexically, and then highest ranked match is selected.

Dockerfile

Add a comment with # x-docker-update: <policy> above your FROM declarations / image names.

Example:

# x-docker-update: >=15, <18
FROM postgres:15.2

Kubernetes Manifest

Add annotations named x-docker-update/<container-name> with the name of the container / image declaration you want to target. Both containers and initContainers entries may be targeted. The container must be named, and the annotation must match the container name for the image. Note that we look for the x-docker-update annotations in the top level annotations even when the images are in deeper templated resources.

Example:

kind: Job
apiVersion: batch/v1
metadata:
  name: my-job
  annotations:
    x-docker-update/job-container: ">=3, <3.15, /slim/"
    x-docker-update/my-init-container: ">=3, <3.14"
spec:
  template:
    spec:
      initContainers:
        - name: my-init-container
          image: python:3.13
          command: >-
            python -c 'print("hello world!")'
      containers:
        - name: job-container
          image: python:3.14.2-slim
          command: "python --version"

docker-compose.yaml

Add an x-docker-update property to the service next to the image you want to update.

Example:

services:
  postgres:
    image: postgres:15.2
    x-docker-update: ">=13, <16"

Motivation

There are a number of projects for maintaining your docker-dependencies. Most of them though require a lot of long lived infrastructure. Long lived infrastructure, push notifications, and cost of these services cause a notification and maintenance burden that were not right for the projects I was working on. I wanted something dead simple that worked like any other open source dependency manager. Update your dependencies when you choose to, save the cryptographic hash to your repo so you have a reproducable, traceable record of your dependencies.

Notes on some alternatives:

• Watchtower

  • Long running process
  • Access to the docker socket
  • Original Archived in December 2025
  • Newest maintained fork is not recommended for the latest versions of docker

• Renovate

  • Long running selfhosted or 3rd hosted process
  • Requires a supported git forge
  • Supports way more than just Docker

• Docker Lock

  • Best of the bunch
  • Original project delisted, fork is hosted here
  • Requires an external lockfile

• Skopeo

  • Awesome Docker image swiss army knife
  • Does not locate and maintain your images for you
  • Could probably hack together the same functionality with Skopeo, yq, and bash, but you are still left to stitch these together yourself.

docker-update is not for you if you need a tool to stay on top of your dependencies for you. We do not push updates to you or notify you that your dependencies are out of date. If you require up-to-the-minute dependencies, this is probably the wrong solution.

Roadmap

• Support private docker registries
• Multi document k8s manifest files