Watchtower Docker Schedule — Cron & Interval Guide

Two Scheduling Methods

Watchtower supports two mutually exclusive docker watchtower schedule methods:

1. WATCHTOWER_POLL_INTERVAL — Simple recurring interval in seconds. Best for homelab or dev environments where exact timing doesn't matter.
2. WATCHTOWER_SCHEDULE — Precise cron expression. Best for production where you want updates only at specific low-traffic times.

WATCHTOWER_POLL_INTERVAL — Simple Interval

Set the watchtower docker interval in seconds with WATCHTOWER_POLL_INTERVAL:

environment:
  - WATCHTOWER_POLL_INTERVAL=3600    # Every 1 hour
  # - WATCHTOWER_POLL_INTERVAL=21600  # Every 6 hours
  # - WATCHTOWER_POLL_INTERVAL=86400  # Every 24 hours (default)

The default is 86400 seconds (24 hours) if neither variable is set. The minimum recommended value is 300 seconds (5 minutes) to avoid rate limiting from Docker Hub.

WATCHTOWER_SCHEDULE — Cron Expression

The watchtower docker cron schedule format uses 6 fields. This is important — standard cron tools use 5 fields, but Watchtower requires 6 with seconds as the first field:

Field	Values	Example
Seconds	0–59	0
Minutes	0–59	30
Hours	0–23	4
Day of Month	1–31 or *	*
Month	1–12 or *	*
Day of Week	0–6 (Sun=0) or *	*

WATCHTOWER_SCHEDULE Cron Examples

# Every day at 4:00 AM
- WATCHTOWER_SCHEDULE=0 0 4 * * *

# Every Sunday at 2:00 AM
- WATCHTOWER_SCHEDULE=0 0 2 * * 0

# Every 6 hours (midnight, 6am, noon, 6pm)
- WATCHTOWER_SCHEDULE=0 0 */6 * * *

# Every weekday (Mon-Fri) at 3:30 AM
- WATCHTOWER_SCHEDULE=0 30 3 * * 1-5

# Every hour at :15 minutes
- WATCHTOWER_SCHEDULE=0 15 * * * *

# First day of every month at 1 AM
- WATCHTOWER_SCHEDULE=0 0 1 1 * *

Watchtower Docker Run Once Mode

The watchtower docker run once flag tells Watchtower to check and update all containers exactly once, then exit. This is useful for CI/CD pipelines, testing, or scheduled external triggers:

# Via docker run --rm (container removes itself after one run)
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower --run-once

# Via environment variable
docker run -d \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_RUN_ONCE=true \
  containrrr/watchtower

Combined with an external cron job (system cron, CI scheduler, Kubernetes CronJob), this gives you full control over when updates run without Watchtower's built-in scheduler.

Watchtower Docker Run Now — HTTP API Trigger

Trigger an immediate watchtower docker run now update cycle using the HTTP API without restarting Watchtower:

# Enable the HTTP API (add to Watchtower environment)
- WATCHTOWER_HTTP_API_UPDATE=true
- WATCHTOWER_HTTP_API_TOKEN=mySecretToken

# Trigger update via curl
curl -H "Authorization: Bearer mySecretToken" \
  http://watchtower:8080/v1/update

The HTTP API runs Watchtower's update cycle immediately, on demand, while the normal schedule continues in the background.

Timezone Configuration

Cron expressions use the container's timezone, which defaults to UTC. To match your local time, mount the host timezone file:

services:
  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /etc/timezone:/etc/timezone:ro      # Mount host timezone
      - /etc/localtime:/etc/localtime:ro    # Mount localtime
    environment:
      - WATCHTOWER_SCHEDULE=0 0 4 * * *    # Now runs at 4 AM in host's timezone