Skip to content

Introduction

Deprecation Notice

Watchtower v2 Legacy Notification Deprecation

Watchtower has a number of legacy notification configuration options that will be removed with the release of Watchtower v2:

Migration to the NOTIFICATION URL with the appropriate Shoutrrr URL scheme is strongly recommended.

Use Watchtower's CLI migration tool to help convert legacy email configurations to Shoutrrr URLs or use the Shoutrrr Playground to help convert configurations for other services to Shoutrrr URLs.

Overview

By default, Watchtower monitors all containers running on the Docker daemon it connects to (typically the local daemon, configurable via the --host flag).

To limit monitoring to specific containers, provide their names as arguments when starting Watchtower.

services:
    watchtower:
        command: nginx redis
        image: nickfedor/watchtower:latest
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock
docker run -d \
    --name watchtower \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --restart unless-stopped \
    nickfedor/watchtower \
    nginx redis
  • In the above example, Watchtower monitors only the nginx and redis containers, ignoring others.

To run a single update attempt and exit, use the run-once configuration option.

services:
    watchtower:
        command: nginx redis
        environment:
            WATCHTOWER_RUN_ONCE: true
        image: nickfedor/watchtower:latest
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock
docker run --rm \
    -v /var/run/docker.sock:/var/run/docker.sock \
    nickfedor/watchtower \
    --run-once \
    nginx redis
  • This command triggers an update attempt for "nginx" and "redis" containers, displays debug output, and removes the Watchtower container upon completion.

By default, Watchtower decides that an image is stale by comparing registry digests. Git monitoring is an optional alternate staleness signal: associate a container with a hosted repository, and Watchtower rebuilds from a Git URL context or a local Compose project directory when that ref changes. See Advanced Features → Git Monitoring.

Note

Regex patterns are supported. See Regex Pattern Matching for details.

Startup errors

When a configuration option or flag is invalid, Watchtower exits at startup.

  • In a container, Watchtower first sets its restart policy to no, so the container does not restart in a loop.
  • Start the container again once the configuration is fixed.
  • A --host flag after an invalid flag is not read. Watchtower then connects through DOCKER_HOST or the default socket.
  • If Watchtower cannot change its restart policy, it logs an error.

General Options

Help

Displays documentation for supported flags.

            Argument: --help
Environment Variable: N/A
                Type: N/A
             Default: N/A

Health Check

Returns a success exit code for Docker HEALTHCHECK, verifying another process is running in the container.

            Argument: --health-check
Environment Variable: None
                Type: N/A
             Default: N/A

Note

Intended solely for Docker HEALTHCHECK. Do not use on the main command line.

Health Check with Podman

Podman ignores the HEALTHCHECK instruction in the Watchtower image. The image is published in the OCI format, and Podman only reads health checks from images in the Docker format (containers/podman#18904). To enable the health check under Podman, define it in your container configuration, as shown below.

services:
    watchtower:
        image: nickfedor/watchtower:latest
        healthcheck:
            test: ["CMD", "/watchtower", "--health-check"]
        volumes:
            - /run/podman/podman.sock:/var/run/docker.sock
podman run -d \
    --name watchtower \
    --health-cmd '["/watchtower", "--health-check"]' \
    -v /run/podman/podman.sock:/var/run/docker.sock \
    nickfedor/watchtower
[Container]
Image=docker.io/nickfedor/watchtower:latest
HealthCmd=["/watchtower", "--health-check"]
Volume=/run/podman/podman.sock:/var/run/docker.sock

Note

  • Use the exec form shown above. Because the image does not include a shell, a shell-form health check, such as --health-cmd "/watchtower --health-check" or a CMD-SHELL test, always reports the container as unhealthy.
  • Docker Compose requires CMD as the first entry of the test list. Without it, Compose fails with the error healthcheck.test must start either by "CMD", "CMD-SHELL" or "NONE".
  • For rootless Podman, mount the socket from $XDG_RUNTIME_DIR/podman/podman.sock instead of /run/podman/podman.sock.