Do Diun, Watchtower and docker compose pull count against Docker Hub's pull limit?

Mostly no. Diun and Watchtower check for updates with HEAD requests, which Docker says do not count, and a docker compose pull of an image that is already current cost nothing when we measured it. What costs a pull is downloading a new image, one per image per architecture. Two habits drain the budget: Diun's diun.watch_repo=true, and home-made checkers that use GET requests.

The limit is 100 pulls per 6 hours, not 10 per hour#

Docker's documentation gives the current limits per 6 hours:

The other figure you have seen is real but was never applied. By February 2025 Docker's announced plan was that from 1 April 2025 unauthenticated users would be limited to 10 pulls per hour and free accounts to 100 per hour, as The Register reported at the time. Docker then did not enforce it. Its own update of 8 April 2025 says the 100 and 200 per 6 hours limits "will remain in place", and adds: "We will announce any future enforcement at least 6 months in advance." So if you hit a 429 today, the cause is not a secret 10-per-hour rule. It is something in your stack spending pulls faster than you think.

The per-hour number persists for an ordinary reason: it was widely reported, copied into blog posts and CI guides, and nobody goes back to correct a post about a change that did not happen.

What counts as a pull, measured#

Docker's definition has four lines worth knowing: a pull includes a version check plus any download that results from it; version checks do not count; a normal image costs one pull for its single manifest; and a multi-arch image "will count as one pull for each different architecture". Its documentation also says plainly that a GET for a manifest counts and a HEAD does not.

That is the rule. Here is what it costs in practice, measured against the live registry on 7 October 2026 from one server address, unauthenticated, reading ratelimit-remaining before and after each step (Docker Engine 28.1.1, Compose 2.35.1):

The last row is the one nobody writes down. docker manifest inspect is the obvious building block for a cron script that checks for updates, and on a typical official image it costs as much as nine real pulls. A script that runs it hourly against ten such images uses 90 pulls an hour.

Read your own counter before you guess#

The check costs nothing because it is a HEAD request. This is Docker's documented command, run from the machine that pulls:

TOKEN=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token)
curl -s --head -H "Authorization: Bearer $TOKEN" \
  https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest \
  | grep -i '^ratelimit'
# example output:
# ratelimit-limit: 100;w=21600
# ratelimit-remaining: 87;w=21600

w is the window in seconds, so w=21600 is 6 hours. Add --user 'name:token' to the first curl to see an authenticated account's counter instead of your IP's.

One thing we saw that the documentation does not mention: on 7 October 2026 the registry answered our server's address with ratelimit-limit: 100;w=3600, a one-hour window, while the documentation still says six hours. The headers are what the registry enforces against you, so trust them over any page, this one included. Run the check before and after a Diun scan or a nightly pull and you know what each job costs rather than estimating it.

Diun: a HEAD per image, a GET only when something changed#

Diun's registry code makes this explicit. Each scheduled check sends a HEAD to get the remote digest. If it matches the digest stored in Diun's database, the check ends there, and that costs nothing. Only when the digest differs, or the image is new to the database, does Diun GET the manifest to read its metadata, which costs one pull. Diun's own FAQ says the same: it does not GET at each scan, "only when an image has been updated or added on the registry".

So a normal setup is cheap. Forty watched images on a 0 */6 * * * schedule spend nothing on a quiet day and one pull for each image that actually changed.

diun.watch_repo=true breaks that arithmetic. It tells Diun to watch every tag in the repository instead of the one you run, and every tag Diun has never seen is "added", so the first scan fetches a manifest for each. The Diun FAQ warns that it "will fetch manifest for ALL tags". The tag lists themselves are free; it is the per-tag GETs that cost you. Counted on 7 October 2026:

One watch_repo label on Postgres is fourteen times the anonymous budget on the first scan alone, and mutable tags such as 17, 17-alpine and latest keep changing digest, so later scans keep paying. The default for diun.max_tags is 0, which means all of them. If you want watch_repo, bound it:

labels:
  - "diun.enable=true"
  - "diun.watch_repo=true"
  - "diun.max_tags=10"
  - "diun.include_tags=^17\\.\\d+$"

The usual reason for wanting watch_repo is to hear about a new version when you pin exact tags, which is what An update strategy that does not lose data recommends. An include_tags regex for your current major gives you that for a few pulls.

Watchtower: free checks, but monitor-only still downloads#

Watchtower also checks with a HEAD request; its code comments that it does so "to prevent rate limiting". When the digests match it skips the image, which costs nothing.

Two things cost pulls. When the digests differ, Watchtower pulls the new image, and its documentation notes this happens even with WATCHTOWER_MONITOR_ONLY=true: to know what changed it "will still do a pull whenever the repository digest doesn't match". That is one pull per changed image, the same as you would pay updating by hand. And if the HEAD request fails, Watchtower falls back to a regular pull, logged as "Could not do a head request". By default that is a warning only for registries known to rate limit, mainly Docker Hub; WATCHTOWER_WARN_ON_HEAD_FAILURE=always makes it visible everywhere.

The bigger Watchtower question is not pulls at all: the original project was archived in December 2025. Watchtower vs Diun covers that, and why notify-only is the safer default for anything with a database.

docker compose pull costs what it downloads#

A docker compose pull across a stack is a version check per service, and in our measurement a current image cost nothing. So a nightly pull of 20 services usually spends a few pulls, one per image that changed. The cases that do spend real budget:

• First deploys and rebuilt hosts. Every image is new. A 30-service host rebuilt from scratch uses 30 pulls or more in one go, before any retries. Moving a service to a new machine is the moment you will see a 429 if you see one at all.
• Pruning between pulls. docker image prune -a on a schedule removes every image no container uses, so the next pull of any of them downloads again and counts.
• Multi-platform builds. Docker counts one pull per architecture, so a build for amd64 and arm64 that fetches its base images fresh pays for each one twice.

The budget is per address, which at home means per household#

Unauthenticated pulls are counted per IPv4 address or IPv6 /64. Behind a home router, every machine shares one public IPv4 address: the server, the NAS, a laptop running builds and the Proxmox node all spend the same 100. A Diun instance that looks modest can be the thing that tips a CI job on another machine into a 429.

Logging in fixes both problems at once. The count follows the account rather than the address, and the budget doubles to 200. Diun takes credentials as variables:

environment:
  DIUN_REGOPTS_0_NAME: "docker.io"
  DIUN_REGOPTS_0_SELECTOR: "image"
  DIUN_REGOPTS_0_USERNAME: "yourname"
  DIUN_REGOPTS_0_PASSWORDFILE: "/run/secrets/dockerhub_token"

Watchtower reads a mounted config.json produced by docker login, and docker compose pull uses that same login on the host. Use an access token rather than your password, and keep it out of the git-tracked compose file, as Docker Compose conventions describes for every secret.

When this answer stops applying#

• Docker changes the limits. It has promised 6 months' notice. The header check above is how you notice before a guide does.
• Other registries. Images on ghcr.io or a vendor's own registry do not count against Docker Hub at all, and their limits are not covered here.
• The window we observed. Our one-hour w=3600 reading was one address on one day, unauthenticated. We did not measure the authenticated window.
• Watchtower forks. The behavior described is the archived v1.7.1 code. A fork may check differently, so measure it with the header check.

What to do next#

Run the header check now, and again after your update checker's next scan. If the number did not move, your checker is fine and you can stop worrying about this. If it dropped, look for diun.watch_repo labels without max_tags, then for any script calling docker manifest inspect, then log in. Send Diun's notifications somewhere you actually read: ntfy vs Gotify picks the receiver, and The minimum viable monitoring stack covers an alert for the day a pull fails. For whether to update automatically at all, start with An update strategy that does not lose data.