Container Selection

Configuration

Container Selection

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

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

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

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 container 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

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

Enable Containers by Label

Restricts monitoring to containers that have at least one of the specified label key-value pairs.

            Argument: --enable-containers-by-label
Environment Variable: WATCHTOWER_ENABLE_CONTAINERS_BY_LABEL
                Type: Comma-separated list of key=value pairs
             Default: None

Values containing commas are not supported. Use individual key=value pairs separated by commas.

A label entry with an empty value (key=) performs a presence check: the label must exist on the container with any value. A non-empty value requires an exact match.

Disable Containers by Label

Excludes containers that have any of the specified label key-value pairs from monitoring.

            Argument: --disable-containers-by-label
Environment Variable: WATCHTOWER_DISABLE_CONTAINERS_BY_LABEL
                Type: Comma-separated list of key=value pairs
             Default: None

Values containing commas are not supported. Use individual key=value pairs separated by commas.

A label entry with an empty value (key=) performs a presence check: the label must exist on the container with any value. A non-empty value requires an exact match.

Monitor Specific Images

Restricts monitoring to containers whose image name matches one of the supplied image name patterns, even if other selection criteria would include them.

            Argument: --monitor-image-names
Environment Variable: WATCHTOWER_MONITOR_IMAGE_NAMES
                Type: Comma or space-separated string list
             Default: None

Image name patterns include the tag (for example nginx:latest). Regex patterns are supported and anchored to the full image name. See Regex Pattern Matching for details.

Skip Specific Images

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

            Argument: --skip-image-names
Environment Variable: WATCHTOWER_SKIP_IMAGE_NAMES
                Type: Comma or space-separated string list
             Default: None

Image name patterns include the tag (for example nginx:latest). Regex patterns are supported and anchored to the full image name. 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

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.

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

By default, Watchtower automatically detects and respects Docker Compose service dependencies.
When this feature is disabled, only the Watchtower depends-on label, Docker links, and network mode are used.

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.

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, the use-compose-depends-on configuration option controls whether Docker Compose depends_on labels are included in the dependency validation check.

Last updated on August 13, 2026

Docker Connection Scheduling