Skip to content

Build1 publisher3 min readPublished

Registry logs show Compose v5.5.1 ignoring pull_policy windows on explicit pulls

Docker Compose v5.5.1 hit the registry on all three explicit pulls in a developer's test, though its v5.5.0 changelog says pull now honors refresh windows. For CI pipelines built around an explicit pull step, the upgrade bought no fewer registry calls in that test.

The Engineer · Build desk

What happened

  • Under docker compose up, pull_policy: daily produced one registry HEAD request across five back-to-back up and down cycles, against five with pull_policy: always.
  • Against Docker Hub, fetching an anonymous pull token and checking one manifest took between 0.40 and 1.01 seconds over three tries from the author's machine.
  • The pre-fix v5.1.1 binary logged the same three registry checks as v5.5.1 across cold, immediate and post-window pulls with an every_3s policy.
  • Help output for compose pull and compose up is identical between v5.1.1 and v5.5.1, so no new flag exposes whatever changed in the release.
  • The Docker Engine 29.3.1 install used for the test shipped the Compose plugin at v5.1.1, older than the release whose changelog claims the fix.

Compiled by The EngineerSomething wrong?How this is made

Why it matters

  • decision Teams weighing a manual plugin upgrade to trim CI pull steps have no measured saving to justify it; the case needs another reason, or a reproduction that contradicts this one.
  • cost Against Docker Hub the up saving is a few seconds per five cycles, so the policy matters most where registry calls are slow or rate-limited.
  • constraint Services that re-push mutable tags accept a stale image inside the window, because up will not ask the registry again until the window expires.

Under `up`, the saving comes from a time check against the local image. With `pull_policy: every_3s`, an immediate second `up` skipped the registry, and a third `up` after a six-second sleep checked again and re-pulled [8]. The window expires. The author ran that test to rule out a permanent "already pulled" flag [8]. Compose has accepted `daily`, `weekly` and `every_<duration>` since v2.34.0 [2]. The v5.1.1 plugin bundled with Engine 29.3.1 is well past that release, so it already applies the windows during `up` [3].

The explicit pull is where the test and the release notes disagree. The v5.5.0 changelog, released 17 August 2026, says `compose pull` now respects the daily, weekly and every_N refresh windows set in pull_policy [3]. The developer who checked it, writing on dev.to, downloaded the v5.1.1 and v5.5.1 binaries from GitHub [5]. Both ran against a local `registry:2` container holding one small image, with its access log tailed to count manifest checks [5]. It is a clean harness. The count comes from the registry's own log, and the cold start used `docker rmi -f` so no copy of the image stayed on the daemon [13].

The run covered the case the changelog names: plain window values, an explicit `pull`, nothing else in play [16]. Swapping `daily` in for `every_3s` gave the same result [10]. The author saw no difference in behaviour between the pre-fix and post-fix binaries [16]. This is one developer's harness against one local registry, and it is enough to establish that the changelog's named case behaved the same on both binaries there. "I can't tell from the outside what the fix actually touched," the author wrote [15]. On CI the author was plain: "If you were hoping the fix meant your CI pipeline's docker compose pull step would start skipping unnecessary registry calls, it doesn't, at least not in this scenario." [14]

The 80 percent cut under `up` [1] comes from the author's workload: five back-to-back cycles inside one window on a machine that kept the image. It transfers only to a pipeline that calls `up` more than once per window on a runner that keeps its image store between calls [5]. A runner that starts empty repeats the cold first cycle, and in the test that cycle checked the registry [1]. Locally the saving did not show on the clock. Both five-cycle runs took about 53 seconds, mostly container and network setup [6]. Against Docker Hub, four avoided round trips at the measured 0.40 to 1.01 seconds each come to about 1.6 to 4.1 seconds per five cycles [2]. The author wrote that "on a slow or rate-limited registry it adds up over a day of repeated up calls" [17].

The window also costs freshness. "A refresh window that skips checks also skips seeing real changes," the author wrote [12]. Because the skip is time-based, a new image pushed to the same tag inside the window goes unchecked by `up` until the window runs out [4].

What to watch

  • A Compose maintainer explanation or follow-up release note defining which code path the v5.5.0 pull_policy change actually covers.
  • A reproduction of the explicit-pull test against Docker Hub or a private registry, in place of a local registry:2 container.
  • The Compose plugin version bundled with the next Docker Engine release after 29.3.1.
Loading claim ledger
Loading source directory links
Loading share composer
Loading topic controls
Loading related stories