Watchtower Docker Automatic Updates — Complete Guide

How Watchtower Docker Automatic Updates Work

Watchtower docker automatic updates follow a four-step lifecycle that runs on every poll cycle:

1. Poll: Watchtower queries the container registry (Docker Hub by default) for each running container's image. It compares the remote image digest against the locally running digest.
2. Detect: If the remote digest differs (a new image has been pushed), Watchtower flags that container for update.
3. Pull: The new Docker image is downloaded to the host.
4. Replace: The old container is gracefully stopped (using a configurable stop signal and timeout), and a new container is started using the updated image with identical runtime parameters.

This is the complete watchtower docker auto update cycle. It requires no user interaction once configured.

Default Automatic Update Behavior

Out of the box, watchtower auto update docker containers behavior is:

• All running containers are monitored (no opt-in required)
• Check interval: every 86400 seconds (24 hours)
• Old images are not removed (set WATCHTOWER_CLEANUP=true to enable)
• Watchtower updates itself as well
• No notifications sent (add WATCHTOWER_NOTIFICATIONS to enable)

Enabling Automatic Updates

The simplest way to enable watchtower docker auto updates is:

docker run -d \
  --name watchtower \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --cleanup

Or in Docker Compose (watchtower docker auto update containers via Compose):

services:
  watchtower:
    image: containrrr/watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_POLL_INTERVAL=3600  # Check every hour

Auto-Update Specific Docker Containers

To enable watchtower docker automatic container updates for only selected containers, use label-enable mode:

services:
  watchtower:
    image: containrrr/watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_LABEL_ENABLE=true   # Only update labeled containers
      - WATCHTOWER_CLEANUP=true

  # This container WILL be auto-updated
  myapp:
    image: myapp:latest
    labels:
      - "com.centurylinklabs.watchtower.enable=true"

  # This container will NOT be auto-updated
  database:
    image: postgres:15
    # No watchtower label = ignored when LABEL_ENABLE=true

Watchtower Docker Auto Update Documentation Reference

The official watchtower docker automatic updates documentation is maintained at containrrr.dev/watchtower. Key environment variable references for auto-updates:

Monitoring Auto-Update Logs

Monitor watchtower docker auto update logs to see exactly which containers were updated and when:

# Follow live logs
docker logs watchtower --follow

# Sample successful update log output:
# time="2026-05-26" level=info msg="Checking all containers (except explicitly disabled ones)"
# time="2026-05-26" level=info msg="Found new nginx:latest image"
# time="2026-05-26" level=info msg="Stopping /nginx"
# time="2026-05-26" level=info msg="Creating /nginx"
# time="2026-05-26" level=info msg="Removing old image nginx@sha256:old..."

# Filter only update events
docker logs watchtower 2>&1 | grep -i "updated\|new.*image\|stopping"

Best Practices for Docker Auto-Updates

• Schedule off-peak hours: Use WATCHTOWER_SCHEDULE to run updates at 3–5 AM to minimise user impact.
• Enable cleanup: Always set WATCHTOWER_CLEANUP=true to prevent disk exhaustion.
• Use rolling restarts: For multi-container stacks, set WATCHTOWER_ROLLING_RESTART=true to restart one container at a time.
• Exclude critical databases: Add com.centurylinklabs.watchtower.enable=false to stateful services like PostgreSQL or MySQL that require manual upgrade procedures.
• Monitor via notifications: Configure Slack or email alerts so you know immediately when a container is updated or fails to update.