Watchtower by nicholas-fedor: Automated Docker Container Image Updates
Automate Docker container image updates
At a glance
- What is it?
- Watchtower monitors running Docker containers, polls their registries for new images, and automatically restarts each container with the updated image using the same options it was launched with. The project targets homelabs, media centers, and local development environments and explicitly advises against use in commercial or production settings.
- Who is it for?
- Watchtower fits homelabs and media servers where missed updates are inconvenient but a failed restart is not a production incident. The README explicitly warns against using it in commercial or production environments; teams with that requirement should look at Kubernetes with a CD system as the README suggests.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 30, 2026, and from our analysis. They are not legal advice.
Editorial analysis
What Watchtower does and who it is for
Watchtower eliminates the manual step of pulling a new Docker image, stopping the old container, and starting a new one with the same configuration. It runs as a container itself, monitors the other containers on the host, and when a new image is available in the registry, it pulls the image, gracefully shuts down the existing container, and restarts it with the same Docker options that were used at initial deployment.
The README is direct about the intended audience: homelabs, media centers, and local development environments. It is not positioned as a deployment automation tool for services with uptime requirements. The project is maintained by Nicholas Fedor, with additional contributors from the broader container tooling community. The last push was on 2026-09-27, and the three most recent releases are v1.22.3 on 2026-09-22, v1.22.2 on 2026-09-15, and v1.22.1 on 2026-09-09. The documentation site at watchtower.nickfedor.com covers configuration reference, container selection filters, notification services, and the HTTP API in more depth than the README.
Running Watchtower for the first time
The quick start in the README mounts the Docker socket so Watchtower can communicate with the Docker daemon:
$ docker run --detach \
--name watchtower \
--volume /var/run/docker.sock:/var/run/docker.sock \
nickfedor/watchtowerOnce running, Watchtower polls all running containers on the host at a configurable interval. Mounting /var/run/docker.sock gives the container access to the host Docker daemon, which is the mechanism Watchtower uses to inspect, stop, and restart containers. The README recommends using the latest version of Docker and notes that the current Watchtower build has been tested against Docker API version 1.43 and higher. Older Docker versions may produce unexpected behavior when newer API features are used. The docker version CLI command can be used to verify the host's Docker version before deploying.
How the update mechanism works
Watchtower uses the Docker client library to connect to the daemon through the mounted socket. It queries the current containers, checks each image's digest against the registry, and triggers the update cycle when a new digest is found. The restart uses the same options as the original container launch, preserving environment variables, volume mounts, network configuration, and port bindings without requiring the operator to re-specify them.
The Docker API version handling is configurable. By default, Watchtower autonegotiates the API version with the daemon. If the DOCKER_API_VERSION environment variable is explicitly set, Watchtower validates the specified version and falls back to autonegotiation on validation failure. This means a manually set version that does not match the daemon is handled gracefully rather than causing a hard failure. The go.mod specifies the moby/moby/client and moby/moby/api dependencies for this communication layer. The cenkalti/backoff dependency handles retry logic for transient registry communication failures, and the robfig/cron dependency manages the polling schedule.
Supported architectures and image variants
The Docker image at nickfedor/watchtower on Docker Hub supports five architectures: amd64, i386, armhf, arm64v8, and riscv64. The riscv64 support is notable; most container tooling does not publish riscv64 images. This makes Watchtower deployable on a wider range of single-board computers and embedded systems beyond the typical ARM-based Raspberry Pi setups.
The go.mod file specifies go 1.27.1 as the minimum Go version. The repository uses CircleCI for continuous integration and Codecov for coverage tracking, as shown in the README badges. The Makefile at the root defines a build target that compiles the binary:
$(GO) build -o bin/$(BINARY_NAME) ./...And a test target that runs the full test suite with coverage tracking:
$(GO) test -timeout 30s -v -coverprofile coverage.out -covermode atomic ./...Goreleaser handles multi-architecture release builds. The Makefile also defines targets for linting (golangci-lint), Go vet, formatting, mock generation with Mockery, and a tplprev module for template preview testing.
When not to use Watchtower
The README contains an explicit warning: Watchtower is not recommended for commercial or production environments. The reason is the lack of controlled rollout. Watchtower applies updates immediately when a new image appears in the registry, which means a broken image pushed to production would trigger an automatic restart and potentially take a service down without review or staged rollout. There is no dry-run mode described in the README that would show what would be updated before committing to a restart.
For production container workloads, the README itself suggests Kubernetes with a CD system and links to a specific example: onedr0p's Talos Linux with FluxCD setup. That approach separates image build from deployment, allows canary releases, and provides rollback through version-controlled manifests. Watchtower has no concept of rollback; once a container is restarted with a new image, returning to the previous version requires a manual intervention or pushing a previous image back to the registry with the expected tag.
Advanced features: HTTP API, lifecycle hooks, and metrics
The examples/ directory contains subdirectories for default, http-api, lifecycle-hooks, and metrics, indicating that Watchtower supports these as optional configurations. The gofiber/fiber dependency in go.mod is the HTTP server framework used for the HTTP API. The prometheus/client_golang dependency handles the metrics endpoint, and the nicholas-fedor/shoutrrr dependency handles notifications. The swaggo/swag dependency generates API documentation for the HTTP API.
The full documentation at watchtower.nickfedor.com covers these features in detail. The HTTP API allows external systems to trigger update checks on demand rather than waiting for the polling interval. Lifecycle hooks execute scripts or commands before and after container updates, which is useful for draining connections from a load balancer before a restart or warming a cache after one. Metrics expose Prometheus-compatible data that can be scraped for monitoring update frequency and failures. The maypok86/otter/v2 dependency provides an in-memory cache layer for registry digest lookups, reducing the number of registry API calls during polling cycles.
Maintenance, license, and governance
Watchtower is published under the Apache-2.0 license, which permits commercial and private use, modification, and distribution. The SECURITY.md file covers responsible disclosure. The CHANGELOG.md and cliff.toml at the root indicate the project uses git-cliff for automated changelog generation from conventional commits.
The go.mod specifies `retract [v1.7.2, v1.7.9]`, indicating that several earlier versions were prematurely published and should not be used. The three recent releases in September 2026 suggest a currently active maintenance cadence: v1.22.1 on 2026-09-09, v1.22.2 on 2026-09-15, and v1.22.3 on 2026-09-22. Contributors are tracked through an all-contributors configuration file (.all-contributorsrc), and the repository uses Codacy for code quality grades alongside CircleCI for build verification. The .devcontainer/ directory and .editorconfig indicate the project supports a standardized development environment for contributors.
Editorial conclusion
Watchtower fits homelabs and media servers where missed updates are inconvenient but a failed restart is not a production incident. The README explicitly warns against using it in commercial or production environments; teams with that requirement should look at Kubernetes with a CD system as the README suggests. Before deploying, verify that your Docker installation is version 1.43 or higher and review whether automatic restarts are appropriate for all containers on the host, since Watchtower monitors every container by default unless configured otherwise.
Frequently asked questions
How do I use Watchtower with Docker?
Run Watchtower as a container with the Docker socket mounted: `docker run --detach --name watchtower --volume /var/run/docker.sock:/var/run/docker.sock nickfedor/watchtower`. Once running, it monitors all containers on the host and restarts each one when a new image is available in its registry.
How do I install Watchtower with Docker?
The README shows a single docker run command as the installation step: pull the nickfedor/watchtower image and run it with the Docker socket mounted as a volume. No separate binary installation is needed; Watchtower runs entirely as a container alongside the containers it monitors. The repository also provides a Makefile build target for compiling the binary directly from the Go source.
How do I use Watchtower inside Portainer?
Portainer is a Docker management interface, and Watchtower is deployed as a standard container within it. Use Portainer's container creation UI to specify the nickfedor/watchtower image, mount /var/run/docker.sock to /var/run/docker.sock, and set detached mode. The full documentation at watchtower.nickfedor.com covers additional environment variable configuration options that control polling interval, notification services through shoutrrr, and which containers to monitor.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/nicholas-fedor-watchtower)