Watchtower Environment Variables: The Setup Guide You Need

If you are using Watchtower, you already know it can automatically update your Docker containers. But what most users miss is this: The real control does not come from running Watchtower, it comes from configuring it.

And that is where Watchtower environment variables become essential.

They let you define how updates happen, when they run, which containers are included, and even how you get notified. Without them, Watchtower is just basic automation. With them, it becomes a controlled, production-ready system.

This guide breaks it down clearly, so you can actually use these variables with confidence.

What Are Watchtower Docker Environment Variables?

Environment variables are simple key-value settings you pass into a container to control its behavior. In Watchtower, they act as your configuration layer instead of hardcoding flags into commands, you define behavior using variables like:

• WATCHTOWER_POLL_INTERVAL
• WATCHTOWER_CLEANUP
• WATCHTOWER_NOTIFICATIONS

This makes your setup:

• easier to manage
• cleaner in Docker Compose
• more flexible for scaling

Think of environment variables as your control panel for Watchtower.

Why Environment Variables Matter More Than Flags

You can configure Watchtower using CLI flags. But environment variables are better in almost every real-world scenario.

Here is why:

1. Cleaner Configuration

Instead of long, messy commands, you keep everything structured inside your Docker Compose file.

2. Easier Updates

You can tweak behavior without rewriting your run command.

3. Better for Teams

Environment variables are easier to read, review, and version-control.

4. More Scalable

If you are managing multiple containers or environments (staging, production), variables make it manageable.

How to Use Watchtower Docker Environment Variables

You typically define them inside your Docker Compose file:

services:
  watchtower:
    image: containrrr/watchtower
    environment:
      - WATCHTOWER_POLL_INTERVAL=300
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_INCLUDE_STOPPED=false
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

That is it. Watchtower reads these values on startup and adjusts its behavior accordingly.

Core Watchtower Environment Variables (You Should Know)

Let us go beyond surface-level and focus on the ones that actually matter in real setups.

Update Scheduling & Frequency

These control when Watchtower checks for updates.

WATCHTOWER_POLL_INTERVAL

Defines how often Watchtower checks for new images (in seconds).

Example:

WATCHTOWER_POLL_INTERVAL=300

This means that check every 5 minutes Use this when you want simple interval-based updates.

WATCHTOWER_SCHEDULE

Lets you define a cron-style schedule.

Example:

WATCHTOWER_SCHEDULE=0 0 4 * * *

This runs every day at 4 AM Better for production where timing matters. Use either interval or schedule, not both.

Container Control & Scope

These define which containers Watchtower touches.

WATCHTOWER_INCLUDE_STOPPED

• true → includes stopped containers
• false → ignores them

WATCHTOWER_LABEL_ENABLE

Only updates containers with a specific label.

Example:

WATCHTOWER_LABEL_ENABLE=true

This pairs with container labels like:

labels:
  - com.centurylinklabs.watchtower.enable=true

If you want stricter control, this is essential.

WATCHTOWER_SCOPE

Allows multiple Watchtower instances with different scopes. Useful when:

• managing different environments
• isolating update behavior

Cleanup & Resource Management

These variables prevent your system from getting cluttered.

WATCHTOWER_CLEANUP

Removes old images after updating.

WATCHTOWER_CLEANUP=true

Without this, your disk slowly fills with unused images.

WATCHTOWER_REMOVE_VOLUMES

Removes associated volumes when containers are deleted. Use carefully, this can remove data.

Logging & Output Control

These help you understand what Watchtower is doing.

WATCHTOWER_DEBUG

Enables detailed logs.

WATCHTOWER_DEBUG=true

Use this when:

• troubleshooting issues
• verifying update behavior

WATCHTOWER_LOG_LEVEL

Controls verbosity (e.g., info, debug, warn)

Notifications & Alerts

If you are running production workloads, this is critical.

WATCHTOWER_NOTIFICATIONS

Defines notification service (e.g., email, Slack, Discord).

WATCHTOWER_NOTIFICATION_URL

The endpoint for sending notifications.

Example:

WATCHTOWER_NOTIFICATION_URL=slack://token@channel

This allows:

• instant alerts when updates happen
• visibility into failures

Authentication (Private Registries)

If you are pulling from private registries, Watchtower needs access.

REPO_USER & REPO_PASS

Credentials for authentication.

DOCKER_CONFIG

Path to Docker config file for registry access.

If you are working with private images, this section is not optional. Without proper authentication, Watchtower simply will not pull updates.

Real-World Configuration Examples

Let us bring this together.

Example 1: Simple Auto Updates (Beginner Setup)

<

environment:
- WATCHTOWER_POLL_INTERVAL=300
  - WATCHTOWER_CLEANUP=true

Best for:

• small setups
• personal projects

Example 2: Production-Safe Setup

environment:
- WATCHTOWER_SCHEDULE=0 0 3 * * *
  - WATCHTOWER_LABEL_ENABLE=true
  - WATCHTOWER_CLEANUP=true
  - WATCHTOWER_NOTIFICATIONS=slack

Best for:

• controlled updates
• zero surprises

Example 3: Debugging Setup

environment:
- WATCHTOWER_DEBUG=true
  - WATCHTOWER_LOG_LEVEL=debug

Best for:

• troubleshooting
• verifying updates

Common Mistakes to Avoid

Even experienced users get these wrong.

1. Using Too Many Variables Without Understanding Them

It is tempting to copy-paste a full list of variables, but that often creates unpredictable behavior. Some variables override others, while some only work in specific contexts. Start with a minimal setup, understand each variable, then expand intentionally.

2. Mixing Schedule and Poll Interval

Using both WATCHTOWER_SCHEDULE and WATCHTOWER_POLL_INTERVAL can make update behavior unclear. One follows a fixed interval, the other follows a defined time pattern. Choose one method so your update timing stays predictable and easy to reason about.

3. Ignoring Labels in Production

Running Watchtower without label filtering means every container becomes eligible for updates. This can lead to unexpected restarts, especially for critical services. In production, always combine environment variables with label-based control to decide exactly what gets updated.

4. Skipping Cleanup

Without cleanup enabled, old images accumulate silently in the background. Over time, this can consume significant disk space and affect system performance. Enabling cleanup keeps your environment lean and avoids maintenance headaches later.

5. Forgetting Docker Socket Mount

Watchtower relies on access to the Docker socket to monitor and update containers. If /var/run/docker.sock is not mounted, it simply cannot function, regardless of your environment variables. Always verify this before troubleshooting anything else.

When to Use Environment Variables vs CLI Flags

Use environment variables when:

• using Docker Compose
• managing long-term setups
• working in teams

Use CLI flags when:

• testing quickly
• running one-off commands

In most real deployments, environment variables win.

Best Practices for Using Watchtower Environment Variables

If you want a stable, predictable setup:

• Start with minimal config
• Add labels for control
• Use scheduled updates in production
• Enable cleanup by default
• Set up notifications early

The goal is not automation, it is controlled automation.

Conclusion

Watchtower works out of the box but it only becomes truly reliable when you configure it properly.

Watchtower Docker environment variables give you that control. They let you decide:

• when updates happen
• what gets updated
• how your system behaves

Set them thoughtfully, and Watchtower becomes a powerful, predictable part of your infrastructure, not a source of surprises.

FAQ Section