Watchtower Docker Force Update — Trigger Immediately, Clean Up Old Images

Method 1: Force Update with --run-once

The fastest way to force update Docker containers with Watchtower is the --run-once flag. This starts a temporary Watchtower instance, runs one update cycle against all containers, and exits:

# Force update all containers immediately
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower --run-once

# Force update with cleanup (remove old images after update)
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_CLEANUP=true \
  containrrr/watchtower --run-once

# Force update a specific container only
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower --run-once mycontainername

# Force update with debug output to see what's happening
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower --run-once --debug

The --rm flag removes the temporary container after it exits, keeping your Docker environment clean. This command works regardless of whether you have a running Watchtower daemon — it's a completely independent one-shot execution.

Method 2: HTTP API Trigger (Running Daemon)

If you have a Watchtower daemon already running and want to trigger a Watchtower update now without waiting for the next scheduled check, use the HTTP API:

# Step 1: Configure Watchtower with HTTP API enabled
services:
  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_HTTP_API_UPDATE=true
      - WATCHTOWER_HTTP_API_TOKEN=mySecureToken123
      - WATCHTOWER_SCHEDULE=0 0 4 * * *     # Normal scheduled check at 4 AM
    ports:
      - "8080:8080"                          # Expose the API port

# Step 2: Trigger an immediate update via curl
curl -X POST \
  -H "Authorization: Bearer mySecureToken123" \
  http://localhost:8080/v1/update

# Response: HTTP 200 with JSON body showing update results

The HTTP API trigger is perfect for CI/CD pipelines — after pushing a new Docker image to your registry, your pipeline can call this endpoint to immediately deploy the update to running containers.

Run Watchtower Manually via Docker Exec

Another way to run Watchtower manually against a specific container is to send a signal to the running Watchtower process, or simply restart the container to trigger an immediate check on the next startup cycle:

# Restart running Watchtower (triggers immediate check on startup if configured)
docker restart watchtower

# OR: Run a second one-shot instance targeting specific containers
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower --run-once nginx redis postgres

Remove Old Docker Images After Update

When Watchtower updates a container, the old image stays on disk by default. Over time with many containers and frequent updates, this wastes significant disk space. There are three approaches to remove old images with Watchtower:

Option 1: WATCHTOWER_CLEANUP (Recommended)

environment:
  - WATCHTOWER_CLEANUP=true   # Auto-remove old image after each successful update

Option 2: Per-container cleanup label

# Add to a specific container to enable cleanup only for that container
labels:
  - "com.centurylinklabs.watchtower.enable=true"
# Then run Watchtower with cleanup:
environment:
  - WATCHTOWER_CLEANUP=true

Option 3: Manual Docker image prune

# Remove all unused images (those not referenced by any container)
docker image prune -a

# Remove only dangling images (untagged, disconnected from containers)
docker image prune

# With --run-once + cleanup in a scheduled cron job
0 5 * * * docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_CLEANUP=true containrrr/watchtower --run-once

Watchtower Docker Self-Update

Watchtower can update itself — when a new version of containrrr/watchtower is published on Docker Hub, Watchtower will detect it on its next scheduled check and restart itself with the new image.

# Watchtower will update itself if:
# 1. It is running as a regular Docker container (not Swarm service)
# 2. The containrrr/watchtower image has a newer version on Docker Hub
# 3. No exclude label is applied to the Watchtower container itself

# To PREVENT Watchtower from updating itself (pin the version):
services:
  watchtower:
    image: containrrr/watchtower:1.7.1   # Pinned version won't self-update
    # OR add the exclude label:
    labels:
      - "com.centurylinklabs.watchtower.enable=false"

CI/CD Pipeline Integration

A common Watchtower Docker trigger pattern in CI/CD is to push a new image and immediately notify Watchtower to deploy it:

# Example: GitHub Actions step after building and pushing image
- name: Trigger Watchtower update
  run: |
    curl -f -X POST \
      -H "Authorization: Bearer ${{ secrets.WATCHTOWER_TOKEN }}" \
      https://myserver.example.com:8080/v1/update
  env:
    WATCHTOWER_TOKEN: ${{ secrets.WATCHTOWER_API_TOKEN }}

# GitLab CI equivalent
deploy:
  stage: deploy
  script:
    - curl -f -X POST
        -H "Authorization: Bearer ${WATCHTOWER_TOKEN}"
        https://myserver.example.com:8080/v1/update

This pattern eliminates the need to SSH into your server to deploy — push to your registry, trigger Watchtower, and the update is live within seconds.

Update a Specific Container Only

To update a specific Docker container with Watchtower without updating all others:

# Pass container names as arguments to --run-once
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower --run-once nginx

# Multiple specific containers
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower --run-once nginx redis vaultwarden

# Combined with cleanup
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_CLEANUP=true \
  containrrr/watchtower --run-once myapp