URL: Documentation on docs.podman.io
Podman has a service, that can be enabled on a per user basis, that allows podman to automatically update a container, when it detects a new version of the container image. This service is called podman-auto-update and is installed with podman, along side a .timer file aswell.
The service:
$ systemctl --user status podman-auto-update.service
○ podman-auto-update.service - Podman auto-update service
Loaded: loaded (/usr/lib/systemd/user/podman-auto-update.service; disabled; preset: disabled)
Active: inactive (dead)
Docs: man:podman-auto-update(1)
The timer:
$ systemctl --user status podman-auto-update.timer
○ podman-auto-update.timer - Podman auto-update timer
Loaded: loaded (/usr/lib/systemd/user/podman-auto-update.timer; disabled; preset: disabled)
Active: inactive (dead)
Trigger: n/a
Triggers: ● podman-auto-update.service
To enable auto updating of podman Quadlet containers, we need to enable the SystemD timer. This needs to be done on a per user basis.
$ systemctl --user enable --now podman-auto-update.timer
Created symlink /home/ramiraz/.config/systemd/user/timers.target.wants/podman-auto-update.timer → /usr/lib/systemd/user/podman-auto-update.timer.
The timer should now be enabled. Check it to make sure.
$ systemctl --user status podman-auto-update.timer
● podman-auto-update.timer - Podman auto-update timer
Loaded: loaded (/usr/lib/systemd/user/podman-auto-update.timer; enabled; preset: disabled)
Active: active (waiting) since Sat 2025-03-01 14:43:11 CET; 1min 19s ago
Until: Sat 2025-03-01 14:43:11 CET; 1min 19s ago
Trigger: Sun 2025-03-02 00:01:49 CET; 9h left
Triggers: ● podman-auto-update.service
Mar 01 14:43:11 podmanhost systemd[1089]: Started Podman auto-update timer.
To enable auto updating a container, we need to tell podman that the podman-auto-update service should keep track of this container.
The way this is done is different, depending on whether we use podman run or Podman Quadlets to handle our containers. It is technically possible to use this with compose files, but it is not recommended, since it requires a PODMAN_SYSTEMD_UNIT label to be added, to create a SystemD unit file for the container. (See this github issue for more details on this ).
podman run way.We enable autoupdate on our container, at creation time, by adding --label "io.containers.autoupdate=registry|image|local to the podman run command.
podman run --label "io.containers.autoupdate=registry" -d -p 3001:3001 -v uptime-kuma:/app/data:Z --name=uptime-kuma docker.io/louislam/uptime-kuma:latest
We cannot add this to an already running container with podman run. The container would have to be discarded, and then created anew.
To enable auto updating for a container run as podman Quadlet, we need to add AutoUpdate=registry|image|local to our .container file, in the [Container] section.
[Container]
Image=registry.fedoraproject.org/fedora:latest
Exec=sleep infinity
AutoUpdate=registry
As shown in the examples, we use only one of these update policies. They are different ways of handling the auto updating process.
registry policy, Podman reaches out to the container registry to check whether a new image is available. For instance, Podman can compare registry.access.redhat.com/ubi8:8.4 on the registry with the image in the local storage. If they differ, the registry image is considered newer and is pulled down.image update policy, is the older version of the registry policy. It is kept around for backwards compatibility.local policy is slightly different. Podman will not reach out to the registry but will only compare local images. For instance, if a local image has been rebuilt, containers using the previous image can easily be auto-updated.By default the timer is set to run once daily, around midnight (with a randomized delay of 900 seconds.). If we want to change when this happens, we can edit the timer file with the following command:
systemctl --user edit podman-auto-update.timer
Editing timers is complicated, but there’s a helpful article and systemd.timer man page .
This creates a dropin file, where the changes are present. This file can be found here: $HOME/.config/systemd/user/podman-auto-update.timer.d/override.conf
Example of a change, that tells the timer to run every 60 seconds:
### Editing /home/ramiraz/.config/systemd/user/podman-auto-update.timer.d/override.conf
### Anything between here and the comment below will become the new contents of the file
[Timer]
OnActiveSec=60
### Lines below this comment will be discarded
### /usr/lib/systemd/user/podman-auto-update.timer
# [Unit]
# Description=Podman auto-update timer
#
# [Timer]
# OnCalendar=daily
# RandomizedDelaySec=900
# Persistent=true
#
# [Install]
# WantedBy=timers.target
We can check the logs for the last run of the Podman Auto Update service by using journalctl.
$ journalctl --user -xeu podman-auto-update
Mar 01 15:02:04 podmanhost systemd[1089]: Starting Podman auto-update service...
░░ Subject: A start job for unit UNIT has begun execution
░░ Defined-By: systemd
░░ Support: https://wiki.rockylinux.org/rocky/support
░░
░░ A start job for unit UNIT has begun execution.
░░
░░ The job identifier is 335.
Mar 01 15:02:04 podmanhost podman[14765]: 2025-03-01 15:02:04.972928942 +0100 CET m=+0.102281038 system auto-update
Mar 01 15:02:07 podmanhost podman[14765]: UNIT CONTAINER IMAGE >
Mar 01 15:02:07 podmanhost podman[14765]: stirlingPDF.service 0b9401252b8e (stirlingPDF-Quadlet) docker.io/frooodle/s-pdf:latest>
Mar 01 15:02:07 podmanhost podman[14765]: freshrss.service bf2e911ea293 (FreshRSS-Quadlet) lscr.io/linuxserver/freshrss:la>
Mar 01 15:02:07 podmanhost podman[14765]: deluge.service fe158c199c76 (Deluge-Quadlet) lscr.io/linuxserver/deluge:late>
Mar 01 15:02:08 podmanhost podman[14778]: f66633a7bfced9fda269d6a3b53dad54ffb9a4ddaba7717eb8b963b8b10348c9
Mar 01 15:02:08 podmanhost podman[14778]: 2025-03-01 15:02:07.746765114 +0100 CET m=+0.030810270 image remove f66633a7bfced9fda269d6a3b53dad54>
Mar 01 15:02:08 podmanhost systemd[1089]: Finished Podman auto-update service.
░░ Subject: A start job for unit UNIT has finished successfully
░░ Defined-By: systemd
░░ Support: https://wiki.rockylinux.org/rocky/support
░░
░░ A start job for unit UNIT has finished successfully.
░░
░░ The job identifier is 335.
The service checks automatically if there is an updated version of a container image, when the timer triggers it.
However it is possible to run this check manually (without triggering the actual updating).
This is done with this command:
$ podman auto-update --dry-run --format "{{.Image}} {{.Updated}}"
docker.io/frooodle/s-pdf:latest false
lscr.io/linuxserver/deluge:latest pending
lscr.io/linuxserver/freshrss:latest false
We can also trigger the update process manually, if we want to force the update.
This is done with this command:
$ podman auto-update
Trying to pull lscr.io/linuxserver/deluge:latest...
Getting image source signatures
Copying blob e1cde46db0e1 skipped: already exists
Copying blob f521569bbd51 done |
Copying blob 77fd0d4b3ea4 done |
Copying blob b8828f26450d done |
Copying blob e7a93f6e7528 done |
Copying blob d3d4abc4320c done |
Copying blob 0b7d2d56f6ee done |
Copying blob 23c280e02079 done |
Copying blob 4e98e82fcc17 done |
Copying blob c8d29932bf16 done |
Copying config 293687cd01 done |
Writing manifest to image destination
UNIT CONTAINER IMAGE POLICY UPDATED
deluge.service a5fffcb3354d (Deluge-Quadlet) lscr.io/linuxserver/deluge:latest registry true
freshrss.service bf2e911ea293 (FreshRSS-Quadlet) lscr.io/linuxserver/freshrss:latest registry false
stirlingPDF.service 0b9401252b8e (stirlingPDF-Quadlet) docker.io/frooodle/s-pdf:latest registry false
Using AutoUpdate=local in the container file, will allow the podman auto update service, to only update the container, if there is a newer version of the image, on the host itself. This means that the auto Update service will not reach out to the image registry, to see if there is a new version. To trigger an update, the next time the podman-auto-update service runs, we need to pull the newer version of the image ourselves.
This will ofcouse only work with container images with the “:latest” label. If we pin a specific version (ex: v.1.0.1), then it will never autoupdate to a newer version than the pinned version.