Watchtower Docker Run Command: Examples + Best Practices

If you are trying to automate container updates with Watchtower, everything starts with one thing: the docker run command.

Get this part right, and your setup works smoothly. Get it wrong, and you either update nothing or update everything without control.

This guide breaks down the watchtower docker run command in a way that actually makes sense. You will learn:

• what the command really does
• how to structure it properly
• which flags actually matter
• when to use manual runs vs automation

What the Watchtower Docker Run Command Actually Does

At its core, the command does one simple job. It runs a container that watches your other containers for updates. When a new image is available, Watchtower:

• pulls the latest image
• stops the old container
• starts a new one with the updated image

That is it. No hidden logic. No magic layer. But how it behaves depends entirely on how you run it.

Basic Watchtower Docker Run Command (Minimal Setup)

Here is the simplest version:

docker run -d \
--name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower

What each part means:

• -d → runs in background
• --name watchtower → assigns a container name
• -v /var/run/docker.sock:/var/run/docker.sock → gives access to Docker API
• containrrr/watchtower → the official image

Important

Without the Docker socket mount, Watchtower cannot see or update anything. This is the most common mistake.

Why the Docker Socket Matters

Watchtower does not connect to Docker remotely. It directly communicates with the Docker daemon through:

/var/run/docker.sock

This allows it to:

• list containers
• check running images
• pull updates
• restart containers

If this mount is missing or incorrect:

• updates fail
• containers are ignored
• logs show connection errors

Adding Real Control to the Run Command

The basic command works. But it is too broad for real setups. You need control.

Example with label-based filtering:

docker run -d \
--name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --label-enable

What this changes:

Now Watchtower will only update containers that have this label:

com.centurylinklabs.watchtower.enable=true

This prevents:

• accidental updates
• breaking critical services
• updating everything blindly

Running Watchtower on a Schedule

By default, Watchtower checks for updates continuously. That is not ideal. Instead, use a schedule:

docker run -d \
--name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --schedule "0 0 4 * * *"

This means that it will run every day at 4 AM.

Why scheduling matters:

• avoids random restarts
• gives predictable update windows
• safer for production setups

Watchtower Docker Run Once (Manual Execution)

Sometimes you do not want automation. You just want:

• check for updates
• apply them once
• exit

Here is the command:

docker run --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --run-once

What happens:

• runs once
• updates containers if needed
• exits immediately

When to use this:

• before deployments
• during maintenance windows
• in CI/CD pipelines
• testing updates safely

Understanding Key Flags That Actually Matter

Most flags are optional. But a few directly impact behavior.

1. --label-enable

Only update labeled containers. Best for controlled environments.

2. --schedule

Runs updates at defined times. Best for predictable operations.

3. --run-once

Runs a single update cycle and exits. Best for manual workflows.

4. --cleanup

Removes old unused images after updates. Use this carefully:

• saves disk space
• removes rollback safety

5. --interval

Alternative to schedule. Runs every X seconds. Example:

--interval 86400

Runs once every 24 hours.

Real-World Command Examples

1. Safe Production Setup

docker run -d \
--name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --label-enable \
  --schedule "0 0 4 * * *"

Why this works:

• updates only selected containers
• runs at controlled time
• avoids unexpected restarts

2. Lightweight Home Server Setup

docker run -d \
--name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower

Why this works:

• simple
• fully automatic
• minimal setup

3. CI/CD Manual Trigger

docker run --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --run-once

Why this works:

• controlled execution
• no background process
• fits automation pipelines

Common Mistakes to Avoid

1. Running Without Labels in Production

This updates everything, which sounds convenient but quickly becomes dangerous.

A single unintended update can restart critical services, break dependencies, or introduce untested changes without warning. Always define clear boundaries using labels.

2. Forgetting the Docker Socket

Without mounting /var/run/docker.sock, Watchtower has no visibility into your containers.

It cannot detect running services, check for updates, or perform restarts, which makes the setup effectively useless. This is the first thing to verify when nothing seems to work.

3. Assuming It “Just Works Safely”

Watchtower does exactly what you tell it to do. It does nothing more or nothing less.

It does not validate updates, test compatibility, or protect you from bad image versions, so blind trust can lead to avoidable failures.

4. Using Continuous Polling Without Control

Frequent polling may seem harmless, but it creates unpredictable update behavior.

Containers can restart at random times, which can disrupt users, workflows, or background jobs. A scheduled approach is usually more stable and easier to manage.

5. Ignoring Logs

When something goes wrong, the logs usually contain the exact reason.

Skipping them leads to guesswork, wasted time, and repeated mistakes, while a quick log check often points directly to the issue.

When to Use Docker Run vs Docker Compose

Use docker run when:

• you want quick setup
• testing configurations
• running one-off commands

Use Docker Compose when:

• managing multiple services
• maintaining structured deployments
• scaling or modifying configurations

For most long-term setups, Compose is cleaner. But for understanding how Watchtower works, docker run is the best starting point.

Conclusion

The watchtower docker run command is simple on the surface, but powerful in practice. Everything depends on how you configure it:

• no flags → full automation
• labels → controlled updates
• schedule → predictable behavior
• run-once → manual execution

There is no single “best” setup. The right command is the one that fits how you want updates to happen.

FAQ Section