Watchtower Docker Run Once: Force Update Containers Manually

Automatic updates sound convenient until they are not. Maybe you want tighter control over production deployments. Maybe you are testing updates before rollout. Or maybe you just do not want containers restarting at random times.

That is where watchtower docker run once works perfectly.

Instead of running continuously, Watchtower can be executed on demand, giving you precise control over when updates happen. And when paired with force update techniques, it becomes a powerful tool for safe, intentional container management.

This guide walks you through exactly how to do that clearly, practically, and without unnecessary complexity.

What “Run Once” Means in Watchtower

By default, Watchtower runs as a background service. It periodically checks for new container images and updates them automatically. But with the --run-once flag, Watchtower behaves differently:

• It runs a single update cycle
• Checks for newer images
• Updates containers if needed
• Then exits immediately

No scheduling. No background process. Just a clean, one-time execution. This is ideal when you want:

• Manual control over updates
• Safer production workflows
• Integration with scripts or CI/CD pipelines

Watchtower Docker Run Once (Step-by-Step)

Let us start with the simplest working command:

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

What this does:

• --rm → removes the container after execution
• -v /var/run/docker.sock → allows Watchtower to interact with Docker
• containrrr/watchtower → official image
• --run-once → executes a single update cycle

That is it. No daemon, no scheduling, just a controlled update run.

When You Should Use Run Once

This approach is not just a technical option, it solves real operational problems.

1. Controlled Production Updates

You decide exactly when updates happen, which means no unexpected restarts during peak traffic. This is critical for production environments where uptime and stability directly impact users. Instead of relying on automated checks, you can align updates with your release process. It gives you the confidence to update only when you’re ready.

2. Testing Before Deployment

Run updates in staging first to see how new images behave in a safe environment. This allows you to catch compatibility issues, broken changes, or performance problems early. Once everything looks stable, you can repeat the same process in production. It adds a simple but effective validation layer to your workflow.

3. CI/CD Pipelines

You can integrate Watchtower into your deployment pipeline and trigger updates after a successful build. This ensures containers are updated immediately after new images are pushed, without waiting for scheduled checks. It also keeps your deployment process consistent and automated where needed. At the same time, you still retain control over when the pipeline runs.

4. Maintenance Windows

Updates can be scheduled during low-traffic periods to minimize user impact. This is especially useful for applications that cannot afford downtime during peak hours. By running Watchtower manually, you avoid unexpected interruptions during business-critical times. It helps you balance updates with operational stability.

If you are currently relying on automatic updates, it is worth understanding how they behave differently. 

Watchtower Docker Force Update: What It Really Means

Here is where things get slightly misunderstood. Watchtower does not “force update” in the way people expect. It does not blindly restart containers unless there is a new image available.

So what is a force update in practice?

It means ensuring that Watchtower:

• Pulls the latest image
• Detects changes correctly
• Recreates containers when needed

How to Force Update Containers with Watchtower

1. Ensure Image Pulling Is Enabled

By default, Watchtower checks for new images. But you can explicitly control this behavior:

--no-pull=false

This ensures Watchtower actively pulls the latest version.

2. Use Cleanup for Fresh Deployments

--cleanup

This removes old images after updating, preventing clutter and ensuring you are running only the latest versions.

3. Include Stopped Containers (Optional)

--include-stopped

Useful if you want to update containers that are not currently running.

Example: Run Once + Force Update Setup

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --run-once \
  --cleanup \
  --no-pull=false

This combination ensures:

• A single execution
• Latest images are pulled
• Containers are updated if changes exist
• Old images are removed

Updating Specific Containers Only

You do not always want to update everything. Watchtower lets you target specific containers by name:

containrrr/watchtower --run-once nginx redis

Or use labels for more control:

--label-enable

With labels, you can define which containers are eligible for updates, giving you granular control in larger environments.

Run Once vs Automatic Updates

Let us make the distinction clear:

Feature	Run Once	Automatic Mode
Execution	Manual	Scheduled/continuous
Control	High	Lower
Risk	Minimal (controlled timing)	Higher (unexpected updates)
Use Case	Production, CI/CD	Simple setups, homelabs

There is no “better” option, only what fits your workflow.

Common Mistakes to Avoid

Even experienced users run into these issues, especially when switching from automatic to manual workflows.

1. Expecting Updates Without New Images

Watchtower only updates containers when a newer image is available. If the image hasn’t changed, nothing will happen—even if you run it manually. This often leads to confusion when users expect a forced refresh.

2. Forgetting --run-once

Without the --run-once flag, Watchtower runs continuously instead of exiting after one cycle. This can lead to unintended background updates if you’re expecting a one-time execution. Always double-check your command when running manually.

3. Assuming “Force Update” Means Restart

Watchtower does not restart containers unless it detects a new image. Even with flags, it won’t recreate containers without a valid update trigger. “Force update” is more about ensuring image checks and pulls—not forcing restarts.

4. Missing Docker Socket Mount

The /var/run/docker.sock mount is essential for Watchtower to interact with Docker. Without it, Watchtower cannot detect or manage containers at all. If nothing seems to work, this is one of the first things to check.

Practical Workflow Example

Here is a clean, real-world approach many teams follow:

1. Build and push new image
2. Run Watchtower with --run-once
3. Verify updated containers
4. Monitor logs and stability

This keeps updates:

• predictable
• reversible
• safe

When Run Once Is the Better Choice

Use manual execution when:

• uptime matters
• updates must be verified
• automation feels risky
• you are working in production

Use automatic updates when:

• simplicity matters
• environment is non-critical
• you do not need strict control

Final Thoughts on Control vs Convenience

The watchtower is flexible by design. You can automate everything or control everything. The watchtower docker run once approach sits right in the middle:

• simple enough to use
• powerful enough for production
• controlled enough to avoid surprises

And when combined with smart update handling, it gives you exactly what most setups need: predictable, intentional updates.

Conclusion

If you want fewer surprises and more control, stop relying entirely on automation. Run Watchtower when you decide, not when a schedule does.

Start with a simple --run-once command, layer in force update options, and build a workflow that fits your environment.

FAQ Section