Watchtower: automatic Docker image updates for homelabs
Automate Docker container image updates
At a glance
- What is it?
- nicholas-fedor/watchtower watches your running containers, pulls newer images, and restarts them with the same options. It is aimed at homelabs and dev boxes, and the README says not to run it in production.
- Who is it for?
- Adopt Watchtower if you run a homelab, a media center or a local dev box and want container images refreshed without a manual pull and restart cycle. Do not adopt it for commercial or production workloads: the README says so directly and points at Kubernetes with CI/CD instead.
- 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 November 14, 2026, and from our analysis. They are not legal advice.
Star history
- nicholas-fedor/watchtower4,829 ★ · +345
| Repository | 2026-09-23 | 2026-11-14 |
|---|---|---|
| nicholas-fedor/watchtower | 4.5k | 4.8k |
345 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The problem Watchtower solves in a homelab
A container is a snapshot. Once you have deployed an image, nothing about Docker itself tells you that a newer image exists, and nothing replaces the running container when one appears. The manual loop is familiar: pull, stop, remove, run again with the same flags, volumes, ports and environment variables. Get one flag wrong and you have silently changed the deployment.
Watchtower exists to close that loop. The README states that you can update the running version of a containerized app simply by pushing a new image to Docker Hub or your own registry, and that Watchtower pulls the new image, gracefully shuts down the existing container and restarts it with the same options that were used when it was deployed initially. That last clause is the actual product. Anyone can write a cron job that runs docker pull. Preserving the original deployment configuration across the restart is the part that is easy to get wrong by hand.
The audience is stated plainly. Watchtower is intended for homelabs, media centers, local dev environments and similar setups. The README adds that it does not recommend using Watchtower in a commercial or production environment, and points readers who are in that situation toward Kubernetes with CI/CD, naming onedr0p's Talos Linux with FluxCD cluster template as an example. That is an unusually candid scope statement from a project of this kind, and it should be read as a design boundary rather than marketing modesty.
How the update cycle actually runs
Watchtower is a Go program that talks to the Docker daemon through the socket you mount into it. The quick-start command mounts /var/run/docker.sock, which is how it enumerates containers, inspects their configuration, and asks the daemon to pull and recreate them. It is not a sidecar injected into your workloads; it is a separate container that holds a client connection to the host daemon.
When it decides a container is eligible, the sequence the README describes is pull, graceful shutdown, restart with the original options. The word graceful matters. A shutdown that ignores stop signals can corrupt state in databases and anything else that flushes on SIGTERM.
Connection handling has one detail worth noting. The README states that this version autonegotiates the Docker API version by default, and that if the DOCKER_API_VERSION variable is explicitly set, Watchtower validates the version and falls back to autonegotiation on failure. That fallback behaviour is a sensible choice: a stale pinned API version degrades to negotiation instead of breaking the connection outright. The project also warns that it has been tested to support Docker v1.43 and higher, and that newer features on older daemons may behave unexpectedly.
The repository layout shows where the pieces live. cmd/ holds the entry points, pkg/ and internal/ hold the implementation, docs/ carries the documentation, and examples/ contains directories for default, http-api, lifecycle-hooks and metrics configurations. Those example directories are the clearest signal of what the project considers supported surface area beyond the basic update loop.
Installing Watchtower and running it for the first time
There is no package to install on the host. Watchtower ships as a container image, and the README's quick start is a single docker run. The image is nickfedor/watchtower on Docker Hub, and you must mount the Docker socket for it to do anything at all.
docker run --detach \
--name watchtower \
--volume /var/run/docker.sock:/var/run/docker.sock \
nickfedor/watchtowerRun that and you get a detached container named watchtower with the host socket mounted. If the socket mount is missing or wrong, Watchtower has no daemon to talk to and the update loop cannot start. If you are unsure what your host offers, check the daemon version first, because the README ties supported behaviour to Docker v1.43 and higher.
docker versionThat prints the client and server versions. Compare the server version against the v1.43 floor the README states before you expect newer daemon features to work.
The README documents only the container route; the full documentation is at watchtower.nickfedor.com.
Where Watchtower is the wrong tool
The README's own scope statement is the first limitation, and it is not a hedge. It says Watchtower is not recommended for commercial or production environments. An automatic updater that restarts containers on its own schedule is a poor fit for anything with an availability target, because the restart is not coordinated with your traffic, your migrations or your rollback plan. The README does not document rollback. If a new image is broken, the mechanism you have is whatever the registry still serves, not a version pin Watchtower will honour.
That points at the second issue: image tags. Watchtower acts on what the registry publishes for the tag your container is running. If you deploy a floating tag, you have accepted that the content behind it can change without your involvement. If you deploy a fixed version tag, there is nothing new to pull and the update loop has nothing to do. The tool's usefulness depends entirely on your tagging discipline, and the README does not resolve that tension for you.
Third, the socket mount is a real privilege decision. Mounting /var/run/docker.sock into a container gives that container effective control over the host daemon. The quick-start command does exactly this, and it is the standard pattern for tools in this category, but it should be a conscious choice rather than a line you copy without reading. The repository does include a SECURITY.md, which is the place to look for the project's own position.
Finally, there is the question of what gets updated. A homelab host often runs containers you would rather not have restarted at an arbitrary moment, and the README does not lay out the filtering options. The configuration reference lives at watchtower.nickfedor.com, and that is where you should confirm how to restrict the scope before pointing Watchtower at a host with anything stateful on it.
Watchtower against Kubernetes with a GitOps pipeline
The README names the alternative itself: Kubernetes with CI/CD, citing onedr0p's Talos Linux with FluxCD cluster template. The difference is not one of quality but of where the decision lives. Watchtower makes the update decision at runtime, on the host, based on what the registry currently serves for a tag. A GitOps pipeline makes it at commit time, in a repository, based on a manifest change you reviewed.
The practical consequences diverge. With Watchtower, the running state of your host is the source of truth and it drifts forward on its own. With FluxCD and a cluster template, the repository is the source of truth and the cluster is reconciled toward it. That gives you a review step, a diff, and a commit history for every version change. It also gives you a much larger surface to operate: a cluster, a controller, and a manifest layout. For a single home server running a handful of containers, that is a lot of machinery to adopt for the same outcome.
There is a middle ground that the README does not discuss but the repository layout hints at: the examples directory contains http-api, lifecycle-hooks and metrics configurations. Those suggest Watchtower can be wired into a larger setup rather than left entirely autonomous. If you want notifications or hooks around an update, that is where to look, and it keeps the runtime-decision model while adding observability.
Maintenance, licensing and the cost of upgrading
The repository is not archived, and the last push was on 2026-11-02. Releases are frequent: v1.23.0 on 2026-10-06, v1.23.1 on 2026-10-13, and v1.23.2 on 2026-10-22. A project cutting patch releases weekly is one where the upgrade path is short and the changelog is short too. CHANGELOG.md is at the repository root, and cliff.toml indicates the changelog is generated, so reading it before an upgrade is cheap.
Upgrading Watchtower itself is the same operation it performs on everything else: pull the newer image and restart the container. That is a small irony worth planning for. If Watchtower manages its own update, a bad release can take out the thing that would have fixed it. Pinning the Watchtower container to a specific version and updating it deliberately is the conservative choice, and it costs you nothing in capability.
The licence is Apache-2.0, referenced in the README badge and in LICENSE.md. Apache-2.0 is a permissive licence with an explicit patent grant and a requirement to preserve notices. It does not impose copyleft obligations on your own configuration or on the containers Watchtower manages. This is a description of the licence text, not legal advice; if you are redistributing a modified Watchtower, read LICENSE.md and consult someone qualified.
Go 1.27.3 is the module's declared Go version in go.mod, and go.mod also carries a retract directive for v1.7.2 through v1.7.9, marking those versions as prematurely published. That is a useful reminder that version selection for a tool like this is not a formality.
Editorial conclusion
Adopt Watchtower if you run a homelab, a media center or a local dev box and want container images refreshed without a manual pull and restart cycle. Do not adopt it for commercial or production workloads: the README says so directly and points at Kubernetes with CI/CD instead. Before you rely on it, check your host's Docker version with docker version, because the project states it was tested against v1.43 and higher, and decide what should be excluded from updates.
Frequently asked questions
How do I install Watchtower with Docker?
Run the container with the Docker socket mounted, using the command from the README: docker run --detach --name watchtower --volume /var/run/docker.sock:/var/run/docker.sock nickfedor/watchtower. There is no host package to install; the image is nickfedor/watchtower.
How do I use Watchtower to update my containers?
Once the container is running with the socket mounted, Watchtower pulls newer images, gracefully shuts down the existing container and restarts it with the same options used at initial deployment. You do not issue a command per update; the loop runs on its own.
Can I run Watchtower in Portainer?
The README does not document a Portainer deployment. What it gives is a docker run command that mounts /var/run/docker.sock, and any Portainer setup would need to reproduce that socket mount and the nickfedor/watchtower image.
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)Star history chart for your README
[](https://hysenlabs.com/projects/nicholas-fedor-watchtower)Was this useful?