Arguments¶

Deprecation Notice¶

Watchtower v2 Legacy Notification Deprecation

Watchtower has a number of legacy notification 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 notify-upgrade 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.

docker run -d \
    --name watchtower \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --restart unless-stopped \
    nickfedor/watchtower \
    nginx redis

In this example, Watchtower monitors only the "nginx" and "redis" containers, ignoring others. To run a single update attempt and exit, use the --run-once flag with the --rm option to remove the Watchtower container afterward.

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. Without arguments, Watchtower monitors all running containers.

Note

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

Secrets/Files¶

Certain flags support referencing a file, using its contents as the value, to securely handle sensitive data like passwords or tokens, avoiding exposure in configuration files or command lines.

Flag	Environment Variable	Deprecated
`--http-api-token`	`WATCHTOWER_HTTP_API_TOKEN`	No
`--notification-email-server-password`	`WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD`	Yes
`--notification-gotify-token`	`WATCHTOWER_NOTIFICATION_GOTIFY_TOKEN`	Yes
`--notification-msteams-hook`	`WATCHTOWER_NOTIFICATION_MSTEAMS_HOOK_URL`	Yes
`--notification-slack-hook-url`	`WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL`	Yes
`--notification-url`	`WATCHTOWER_NOTIFICATION_URL`	No

Watchtower v2 Legacy Notification Deprecation

Deprecated flags / environment variables will be removed with the release of Watchtower v2. Use the the NOTIFICATION URL with the appropriate Shoutrrr URL scheme instead.

Example Docker Compose Usage¶

secrets:
  access_token:
    file: access_token

services:
  watchtower:
    secrets:
      - access_token
    environment:
      - WATCHTOWER_HTTP_API_TOKEN=/run/secrets/access_token

Time Zone¶

Sets the time zone for Watchtower's logs and the --schedule flag's cron expressions. Without this setting, Watchtower defaults to UTC.

To specify a time zone, use a value from the TZ Database (e.g., Europe/Rome). Alternatively, mount the host's /etc/localtime file using -v /etc/localtime:/etc/localtime:ro.

            Argument: None
Environment Variable: TZ
                Type: String
             Default: UTC

General Options¶

Help¶

Displays documentation for supported flags.

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

Debug¶

Enables debug mode with verbose logging.

            Argument: --debug, -d
Environment Variable: WATCHTOWER_DEBUG
                Type: Boolean
             Default: false

Note

Equivalent to --log-level debug. As an argument, it does not accept a value (e.g., --debug true is invalid).

See Maximum Log Level.

Trace¶

Enables trace mode with highly verbose logging, including sensitive information like credentials.

            Argument: --trace
Environment Variable: WATCHTOWER_TRACE
                Type: Boolean
             Default: false

Note

Equivalent to --log-level trace. As an argument, does not accept a value (e.g., --trace true is invalid).

See Maximum Log Level.

Warning

Use with caution due to credential exposure.

Maximum Log Level¶

Sets the maximum log level output to STDERR, visible in docker logs when running Watchtower in a container.

            Argument: --log-level
Environment Variable: WATCHTOWER_LOG_LEVEL
     Possible Values: panic, fatal, error, warn, info, debug, trace
             Default: info

Logging Format¶

Specifies the format for console log output.

            Argument: --log-format, -l
Environment Variable: WATCHTOWER_LOG_FORMAT
     Possible Values: Auto, LogFmt, Pretty, JSON
             Default: Auto

Disable ANSI Colors¶

Disables ANSI color escape codes in log output for plain text logs.

            Argument: --no-color
Environment Variable: NO_COLOR
                Type: Boolean
             Default: false

Run Once¶

Triggers a single update attempt for specified containers and exits immediately.

            Argument: --run-once, -R
Environment Variable: WATCHTOWER_RUN_ONCE
                Type: Boolean
             Default: false

Watchtower automatically sets its own restart policy to "no" in run-once mode to prevent unwanted restarts.

Use with --rm to remove the Watchtower container after completion.

Update on Start¶

Performs an update check on startup. If a schedule is configured (via --schedule or --interval), then Watchtower continues with periodic updates.

            Argument: --update-on-start
Environment Variable: WATCHTOWER_UPDATE_ON_START
                Type: Boolean
             Default: false

Note

If used with --run-once, a warning is logged and --run-once takes precedence.

Scheduling & Polling¶

Schedule¶

Defines when and how often Watchtower checks for new images using a 6-field Cron expression.

Example: --schedule "0 0 4 * * *" runs daily at 4 AM.

            Argument: --schedule, -s
Environment Variable: WATCHTOWER_SCHEDULE
                Type: String
             Default: None

Note

Cannot be used with --interval.

Requires a time zone set via TZ or a mounted /etc/localtime file. See Time Zone.

Poll Interval¶

Sets the interval (in seconds) for polling new images.

            Argument: --interval, -i
Environment Variable: WATCHTOWER_POLL_INTERVAL
                Type: Integer
             Default: 86400 (24 hours)

Note

Cannot be used with --schedule. Overrides cron-based scheduling.

HTTP API Periodic Polls¶

Enables periodic updates when HTTP API mode is active, allowing both API-triggered and scheduled updates.

            Argument: --http-api-periodic-polls
Environment Variable: WATCHTOWER_HTTP_API_PERIODIC_POLLS
                Type: Boolean
             Default: false

Note

Requires --http-api-update.

See HTTP API Mode.

Container Management¶

Include Stopped Containers¶

Includes created and exited containers in monitoring and updates.

            Argument: --include-stopped, -S
Environment Variable: WATCHTOWER_INCLUDE_STOPPED
                Type: Boolean
             Default: false

Revive Stopped Containers¶

Restarts stopped containers after their images are updated.

            Argument: --revive-stopped
Environment Variable: WATCHTOWER_REVIVE_STOPPED
                Type: Boolean
             Default: false

Note

Requires --include-stopped.

Include Restarting Containers¶

Includes containers in the restarting state for monitoring and updates.

            Argument: --include-restarting
Environment Variable: WATCHTOWER_INCLUDE_RESTARTING
                Type: Boolean
             Default: false

Disable Container Restart¶

Stops and removes the old containers and creates new ones with the updated image, but does not start the new containers. This is useful when an external system (e.g., systemd) manages the container lifecycle.

            Argument: --no-restart
Environment Variable: WATCHTOWER_NO_RESTART
                Type: Boolean
             Default: false

Warning

Combining --no-restart with --cleanup during Watchtower self-update may leave a renamed Watchtower container running without starting a new one, preventing cleanup of the old image.

Use cautiously for self-updating Watchtower instances and consider external lifecycle management (e.g., Docker Compose) to restart containers manually.

Rolling Restart¶

Restarts containers one at a time to minimize downtime. This is ideal for zero-downtime deployments with lifecycle hooks. When containers have health checks configured, Watchtower waits for each container to become healthy before proceeding to the next one.

            Argument: --rolling-restart
Environment Variable: WATCHTOWER_ROLLING_RESTART
                Type: Boolean
             Default: false

Note

When combined with --cleanup, image cleanup is deferred until all containers are updated, which may temporarily increase disk usage for large numbers of containers (>50). This is typically negligible for homelab setups but monitor disk space on resource-constrained hosts.

If a container fails to become healthy within 5 minutes, Watchtower logs a warning but continues with the next container to avoid blocking the entire update process.

This functionality is currently not supported when used in combination with linked-containers.

This limitation exists because linked-containers require coordinated updates across dependency chains, which conflicts with the incremental nature of rolling restarts.

Cleanup Old Images¶

Removes old images after updating containers to free disk space.

            Argument: --cleanup
Environment Variable: WATCHTOWER_CLEANUP
                Type: Boolean
             Default: false

Note

During Watchtower self-updates, cleanup is deferred to the new container to prevent premature image deletion.

Ensure --no-restart is not used with --cleanup to avoid incomplete updates.

Remove Anonymous Volumes¶

Deletes anonymous volumes when updating containers. Named volumes remain unaffected.

            Argument: --remove-volumes
Environment Variable: WATCHTOWER_REMOVE_VOLUMES
                Type: Boolean
             Default: false

Note

Containers with the Docker AutoRemove option enabled are automatically removed by the Docker daemon after stopping. Watchtower skips explicit removal in such cases. This does not affect named volumes.

Monitor Only¶

Monitors for new images, sends notifications, and runs lifecycle hooks without updating containers.

            Argument: --monitor-only
Environment Variable: WATCHTOWER_MONITOR_ONLY
                Type: Boolean
             Default: false

Note

Images may still be pulled due to Docker API limitations for digest comparison.

Can be set per container via the com.centurylinklabs.watchtower.monitor-only label.

See Label Precedence.

Disable Image Pulling¶

Prevents pulling new images from registries, monitoring only local image cache changes. Useful for locally built images.

            Argument: --no-pull
Environment Variable: WATCHTOWER_NO_PULL
                Type: Boolean
             Default: false

Note

Can be set per container via the com.centurylinklabs.watchtower.no-pull label.

See Label Precedence.

Enable Label Filter¶

Restricts monitoring to containers with the com.centurylinklabs.watchtower.enable label set to true when the --label-enable flag is specified. Without --label-enable, containers with this label set to false are excluded, while others are monitored by default.

            Argument: --label-enable
Environment Variable: WATCHTOWER_LABEL_ENABLE
                Type: Boolean
             Default: false

Note

When --label-enable is unset, containers without the com.centurylinklabs.watchtower.enable label or with it set to true are monitored, and those with false are excluded.

When --label-enable is set, only containers with true are monitored, ignoring those with false or no label.

Disable Specific Containers¶

Excludes containers by name from monitoring, even if they have the enable label set to true.

            Argument: --disable-containers, -x
Environment Variable: WATCHTOWER_DISABLE_CONTAINERS
                Type: Comma- or space-separated string list
             Default: None

Note

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

Scope Filter¶

Monitors containers with a com.centurylinklabs.watchtower.scope label matching the specified value, enabling multiple Watchtower instances.

            Argument: --scope
Environment Variable: WATCHTOWER_SCOPE
                Type: String
             Default: None

Note

Set to none to ignore scoped containers. Without this flag, Watchtower monitors all containers regardless of scope.

For self-updates, ensure all Watchtower containers share the same com.centurylinklabs.watchtower.scope label to guarantee cleanup of renamed containers and old images. Mismatched labels may prevent detection, leaving resources running.

See Running Multiple Instances.

Label Precedence¶

Allows container labels (e.g., com.centurylinklabs.watchtower.monitor-only, com.centurylinklabs.watchtower.no-pull) to override corresponding flags.

            Argument: --label-take-precedence
Environment Variable: WATCHTOWER_LABEL_TAKE_PRECEDENCE
                Type: Boolean
             Default: false

Use Docker Compose Depends-On¶

Enables or disables processing of the Docker Compose depends_on configuration for determining container update order. When enabled (default), Watchtower automatically detects and respects Docker Compose service dependencies. When disabled, only the Watchtower depends-on label, Docker links, and network mode are used.

            Argument: --use-compose-depends-on
Environment Variable: WATCHTOWER_USE_COMPOSE_DEPENDS_ON
                Type: Boolean
             Default: true

Note

Disabling this is useful when you want to prevent Watchtower from automatically using Docker Compose dependencies but still use explicit Watchtower labels or Docker links for ordering. For more information on Watchtower's handling of linked containers, please reference the Linked Containers documentation.

Warning

Rolling restarts are not supported when any container has linked dependencies (including Docker Compose depends_on, Watchtower depends-on labels, Docker links, or network mode dependencies). When --rolling-restart is enabled, --use-compose-depends-on controls whether Docker Compose depends_on labels are included in the dependency validation check.

Ephemeral Self-Update¶

Uses a short-lived orchestrator container to perform Watchtower self-updates instead of the default rename-based approach.

            Argument: --ephemeral-self-update
Environment Variable: WATCHTOWER_EPHEMERAL_SELF_UPDATE
                Type: Boolean
             Default: false

This is an experimental feature.

Note

The ephemeral self-update mechanism is only active when Watchtower is running in normal daemon mode. When Watchtower is started with --run-once (one-shot execution), this flag is ignored because the process exits immediately after the initial update pass and there is no continuously running instance to replace. See Updating Watchtower for details on how this mechanism works.

Registry & Authentication¶

REPO_USER¶

Sets the username for authenticating with a private registry, such as Docker Hub.

            Argument: None
Environment Variable: REPO_USER
                Type: String
             Default: None

Note

Must be used with REPO_PASS to provide valid credentials. Suitable for simple username/password authentication.

For Docker Hub, the registry is implicitly https://index.docker.io/v1/.

REPO_PASS¶

Sets the password for authenticating with a private registry, such as Docker Hub.

            Argument: None
Environment Variable: REPO_PASS
                Type: String
             Default: None

Note

Must be used with REPO_USER.

Can be a password or a personal access token for registries requiring 2FA (e.g., Docker Hub).

Use Docker secrets (e.g., WATCHTOWER_PASS=/run/secrets/repo_pass) or environment files to avoid exposing sensitive data in command lines.

DOCKER_CONFIG¶

Specifies the directory containing the Docker configuration file (config.json) for registry authentication.

            Argument: None
Environment Variable: DOCKER_CONFIG
                Type: String
             Default: `/`

Note

Useful for registries requiring complex authentication (e.g., 2FA on Docker Hub) or credential helpers (e.g., AWS ECR).

Mount the config.json file to the container (e.g., -v ~/.docker/config.json:/config.json) and set this variable to the directory containing the file (e.g., /).

Changes to the mounted file may require a symlink to ensure updates propagate.

See Usage and Private Registries.

Skip Registry TLS Verification¶

Disables TLS certificate verification for registry connections, useful for self-signed certificates or insecure registries.

            Argument: --registry-tls-skip
Environment Variable: WATCHTOWER_REGISTRY_TLS_SKIP
                Type: Boolean
             Default: false

Warning

Use cautiously, as it reduces security. Suitable for testing or private registries.

Minimum Registry TLS Version¶

Sets the minimum TLS version for registry connections, overriding the default (TLS 1.2).

            Argument: --registry-tls-min-version
Environment Variable: WATCHTOWER_REGISTRY_TLS_MIN_VERSION
     Possible Values: TLS1.0, TLS1.1, TLS1.2, TLS1.3
             Default: TLS1.2

Warning

Using older versions of TLS not recommended for security reasons.

Proxy Configuration¶

Watchtower supports HTTP/HTTPS proxies for registry connections by respecting standard environment variables. Set these in the Watchtower container to route requests (e.g., to Docker Hub or private registries) through a proxy. This is useful in environments without direct internet access.

Proxy settings are read from the following variables (uppercase and lowercase variants are supported for compatibility):

            Argument: None
Environment Variable: HTTP_PROXY / http_proxy
                Type: String (e.g., "http://proxy.example.com:3128")
             Default: None

            Argument: None
Environment Variable: HTTPS_PROXY / https_proxy
                Type: String (e.g., "http://proxy.example.com:3128")
             Default: None

            Argument: None
Environment Variable: NO_PROXY / no_proxy
                Type: Comma-separated string (e.g., "localhost,127.0.0.1,internal.example.com")
             Default: None

Note

Proxies may require authentication. Include it in the URL (e.g., http://user:[email protected]:3128), but avoid exposing credentials in the command line by using Docker secrets or environment files instead.

If your proxy uses a self-signed certificate, combine with --registry-tls-skip to disable TLS verification (use cautiously).

For details on how Go handles these variables, see the net/http.ProxyFromEnvironment documentation.

Warn on HEAD Failure¶

Controls warnings for failed HEAD requests to registries. Auto warns for registries known to support HEAD requests (e.g., docker.io) that may rate-limit.

            Argument: --warn-on-head-failure
Environment Variable: WATCHTOWER_WARN_ON_HEAD_FAILURE
     Possible Values: always, auto, never
             Default: auto

Docker Connection¶

Docker Host¶

Specifies the Docker daemon socket to connect to, supporting remote hosts via TCP (e.g., tcp://hostname:port).

            Argument: --host, -H
Environment Variable: DOCKER_HOST
                Type: String
             Default: unix:///var/run/docker.sock

Docker API Version¶

Sets the Docker API version for client-daemon communication.

            Argument: --api-version, -a
Environment Variable: DOCKER_API_VERSION
                Type: String
             Default: Autonegotiated

Note

Falls back to autonegotiation on failure.

Warning

Minimum supported version is Docker v1.23.

Refer to Docker's API version matrix for compatibility.

Enable Docker TLS Verification¶

Enables TLS verification for Docker socket connections.

            Argument: --tlsverify
Environment Variable: DOCKER_TLS_VERIFY
                Type: Boolean
             Default: false

Disable Memory Swappiness¶

Sets memory swappiness to nil for Podman compatibility with crun and cgroupv2, overriding Podman's default of 0.

            Argument: --disable-memory-swappiness
Environment Variable: WATCHTOWER_DISABLE_MEMORY_SWAPPINESS
                Type: Boolean
             Default: false

CPU Copy Mode¶

Controls how CPU settings are copied when recreating containers, addressing Podman compatibility issues with CPU limits. Podman handles NanoCPUs differently than Docker, which can cause container recreation failures.

            Argument: --cpu-copy-mode
Environment Variable: WATCHTOWER_CPU_COPY_MODE
                Type: String
     Possible Values: auto, full, none
             Default: auto

Note

auto: Automatically detects if running on Podman and filters NanoCPUs for compatibility. On Docker, copies all CPU settings.
full: Copies all CPU settings unchanged (original behavior).
none: Strips all CPU limits to avoid compatibility issues.

Use auto in mixed Docker/Podman environments. Use full if running only on Docker and want to preserve all CPU limits. Use none if CPU limits are causing issues and you prefer no limits on recreated containers.

Usage Examples¶

Run Watchtower with automatic CPU compatibility:

docker run -d \
    --name watchtower \
    -v /var/run/docker.sock:/var/run/docker.sock \
    nickfedor/watchtower \
    --cpu-copy-mode auto

Force full CPU copying (Docker-only environments):

docker run -d \
    --name watchtower \
    -v /var/run/docker.sock:/var/run/docker.sock \
    nickfedor/watchtower \
    --cpu-copy-mode full

Strip all CPU limits:

docker run -d \
    --name watchtower \
    -v /var/run/docker.sock:/var/run/docker.sock \
    nickfedor/watchtower \
    --cpu-copy-mode none

HTTP API & Metrics¶

HTTP API Mode¶

Runs Watchtower in HTTP API mode, allowing updates only via HTTP requests, with support for tag-specific filtering (e.g., image=foo/bar:1.0).

            Argument: --http-api-update
Environment Variable: WATCHTOWER_HTTP_API_UPDATE
                Type: Boolean
             Default: false

See the HTTP API documentation for details

HTTP API Token¶

Sets an authentication token for HTTP API requests. Can reference a file for security.

            Argument: --http-api-token
Environment Variable: WATCHTOWER_HTTP_API_TOKEN
                Type: String
             Default: None

HTTP API Metrics¶

Enables a Prometheus metrics endpoint via HTTP.

            Argument: --http-api-metrics
Environment Variable: WATCHTOWER_HTTP_API_METRICS
                Type: Boolean
             Default: false

See the Metrics API documentation for details

HTTP API Containers¶

Enables a read-only endpoint that lists watched containers and their current running image digests.

            Argument: --http-api-containers
Environment Variable: WATCHTOWER_HTTP_API_CONTAINERS
                Type: Boolean
             Default: false

See the HTTP API documentation for details

HTTP API Host¶

Sets the host interface for binding the HTTP API.

            Argument: --http-api-host
Environment Variable: WATCHTOWER_HTTP_API_HOST
                Type: String
             Default: empty (binds to all interfaces)

See the HTTP API Host documentation for details

HTTP API Port¶

Sets the listening port for the HTTP API.

            Argument: --http-api-port
Environment Variable: WATCHTOWER_HTTP_API_PORT
                Type: String
             Default: 8080

See the HTTP API Port documentation for details

HTTP API Rate Limit¶

Sets the maximum number of API requests allowed per minute per IP address for the HTTP API. This helps protect against brute-force attacks while allowing normal API usage.

            Argument: --http-api-rate-limit
Environment Variable: WATCHTOWER_HTTP_API_RATE_LIMIT
                Type: Integer
             Default: 60

Note

Rate limiting is enforced per client IP address and applies to all HTTP API endpoints (/v1/update and /v1/metrics). When the limit is exceeded, the client receives HTTP 429 (Too Many Requests). The burst capacity is fixed at 10 requests to allow short bursts of legitimate activity (e.g., concurrent dashboard updates).

Notifications¶

Notification URL¶

Configures the notification service URL. Can reference a file for sensitive values. Supports multiple URLs via comma-separated values or multiple flags.

             Argument: --notification-url
 Environment Variable: WATCHTOWER_NOTIFICATION_URL
                  Type: String (comma-separated or multiple flags)
               Default: None

Multiple Notification URLs

To send notifications to multiple services simultaneously, you can:

Use comma-separated URLs: --notification-url="discord://xxx,telegram://yyy"
Specify the flag multiple times: --notification-url=discord://xxx --notification-url=telegram://yyy
Use YAML arrays in Docker Compose (recommended)

See Configuring Multiple Notification URLs for detailed examples.

CLI Flags vs Environment Variables

The CLI flag can be called multiple times as CLI arguments; however, defining the environment variable multiple times will NOT work and only the last value will be used.

This is because CLI flags use a StringArray type that supports multiple invocations, while environment variables are simple key-value pairs that get overwritten when defined multiple times.

For environment variables, use comma-separated values or YAML arrays instead.

Notification Split by Container¶

Send separate notifications for each updated container instead of grouping them.

            Argument: --notification-split-by-container
Environment Variable: WATCHTOWER_NOTIFICATION_SPLIT_BY_CONTAINER
                Type: Boolean
             Default: false

Note

When disabled (default), notifications are grouped for all updated containers in a single session. When enabled, a separate notification is sent for each container update.

Notification Email Server Password¶

Watchtower v2 Legacy Notification Deprecation

This flag will be removed with the release of Watchtower v2. Use the NOTIFICATION URL with the appropriate Shoutrrr smtp:// URL instead.

Sets the password for the email notification server. Can reference a file for security.

            Argument: --notification-email-server-password
Environment Variable: WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD
                Type: String
             Default: None

Notification Slack Hook URL¶

Watchtower v2 Legacy Notification Deprecation

This flag will be removed with the release of Watchtower v2. Use the NOTIFICATION URL with the appropriate Shoutrrr discord:// URL instead.

Sets the Slack webhook URL for notifications. Can reference a file for security.

            Argument: --notification-slack-hook-url
Environment Variable: WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL
                Type: String
             Default: None

Notification Microsoft Teams Hook¶

Watchtower v2 Legacy Notification Deprecation

This flag will be removed with the release of Watchtower v2. Use the NOTIFICATION URL with the appropriate Shoutrrr teams:// URL instead.

Sets the Microsoft Teams webhook URL for notifications. Can reference a file for security.

            Argument: --notification-msteams-hook
Environment Variable: WATCHTOWER_NOTIFICATION_MSTEAMS_HOOK_URL
                Type: String
             Default: None

Notification Gotify Token¶

Watchtower v2 Legacy Notification Deprecation

This flag will be removed with the release of Watchtower v2. Use the NOTIFICATION URL with the appropriate Shoutrrr gotify:// URL instead.

Sets the Gotify token for notifications. Can reference a file for security.

            Argument: --notification-gotify-token
Environment Variable: WATCHTOWER_NOTIFICATION_GOTIFY_TOKEN
                Type: String
             Default: None

Notification Template File¶

Specifies the path to a file containing the Shoutrrr text/template for notification messages.

             Argument: --notification-template-file
 Environment Variable: WATCHTOWER_NOTIFICATION_TEMPLATE_FILE
                 Type: String
              Default: None

Disable Startup Message¶

Suppresses the info-level notification sent when Watchtower starts.

            Argument: --no-startup-message
Environment Variable: WATCHTOWER_NO_STARTUP_MESSAGE
                Type: Boolean
             Default: false

Lifecycle & Health¶

Container Stop Timeout¶

Sets the timeout (e.g., 30s) before forcibly stopping a container during updates.

            Argument: --stop-timeout
Environment Variable: WATCHTOWER_TIMEOUT
                Type: Duration (e.g., 30s, 1m, 5m)
              Default: 30s

Note

Bare numeric values (e.g., 60 or 1.5) without a time unit are interpreted as seconds. Using a unit suffix (s, m, etc.) is recommended and required for other time units.

Cooldown Delay¶

Sets a global minimum image age before Watchtower will perform the update.

Image age is determined from the image creation timestamp in the registry config blob. This helps to establish a time buffer against newly pushed images; however, is not a comprehensive security control.

            Argument: --cooldown-delay
Environment Variable: WATCHTOWER_COOLDOWN_DELAY
                Type: String
             Default: (empty / disabled)

Accepted units: h (hours), m (minutes), s (seconds), d (days), w (weeks), M (months, i.e. 30 days).
These can be combined (e.g., 24h, 3d, 1w, 1M, 1w12h).
Leaving the setting empty disables cooldown.

Warning

This setting delays all updates, including critical security patches. Operators should weigh the trade-off between update immediacy and exposure to unverified images.

Note

See Image Cooldown for detailed information on how cooldown works, boundary behavior, per-container labels, limitations, and interaction with other features like --no-pull.

Cooldown Platform OS¶

Overrides the OS used for platform selection when fetching image manifests during cooldown checks. By default, Watchtower uses the runtime OS (e.g., linux).

            Argument: None
Environment Variable: WATCHTOWER_COOLDOWN_PLATFORM_OS
                Type: String
             Default: runtime.GOOS

Note

Useful for cross-platform monitoring (e.g., monitoring Linux containers from a macOS or Windows host). Only affects the cooldown image age check; does not impact Docker's local platform detection.

See Image Cooldown for details on how platform selection works with multi-platform images.

Cooldown Platform Architecture¶

Overrides the architecture used for platform selection when fetching image manifests during cooldown checks. By default, Watchtower uses the runtime architecture (e.g., amd64, arm64).

            Argument: None
Environment Variable: WATCHTOWER_COOLDOWN_PLATFORM_ARCH
                Type: String
             Default: runtime.GOARCH

Note

Useful for cross-platform monitoring (e.g., monitoring arm64 containers from an amd64 host). Only affects the cooldown image age check; does not impact Docker's local platform detection.

See Image Cooldown for details on how platform selection works with multi-platform images.

Cooldown Platform Variant¶

Specifies the platform variant for platform selection when fetching image manifests during cooldown checks. This disambiguates when multiple image index entries share the same OS and architecture but differ by variant (e.g., ARM v7 vs v8).

            Argument: None
Environment Variable: WATCHTOWER_COOLDOWN_PLATFORM_VARIANT
                Type: String
             Default: None

Note

Required only for ARM images with multiple variants (e.g., v7, v8). When not specified and multiple variants exist, Watchtower returns an ambiguous platform match error.

See Image Cooldown for details on how platform selection works with multi-platform images.

Lifecycle UID¶

Sets the default user ID to run lifecycle hooks as when no container-specific UID is specified.

            Argument: --lifecycle-uid
Environment Variable: WATCHTOWER_LIFECYCLE_UID
                Type: Integer
              Default: None

Note

Container-specific labels (com.centurylinklabs.watchtower.lifecycle.uid) take precedence over this global setting.

See Lifecycle Hooks.

Lifecycle GID¶

Sets the default group ID to run lifecycle hooks as when no container-specific GID is specified.

            Argument: --lifecycle-gid
Environment Variable: WATCHTOWER_LIFECYCLE_GID
                Type: Integer
              Default: None

Note

Container-specific labels (com.centurylinklabs.watchtower.lifecycle.gid) take precedence over this global setting.

See Lifecycle Hooks.

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.

Output & Compatibility¶

Programmatic Output (Porcelain)¶

Outputs session results in a machine-readable format (version specified by VERSION).

            Argument: --porcelain, -P
Environment Variable: WATCHTOWER_PORCELAIN
     Possible Values: v1
             Default: None

Note

Equivalent to:

--notification-url logger://
--notification-log-stdout
--notification-report
--notification-template porcelain.VERSION.summary-no-log