Docker Compose recreates containers you didn’t touch the first time you run docker compose up after upgrading to 5.5. That’s expected, not a bug. Compose 5.5 overhauls image digest reconciliation — the logic that decides whether an existing container matches what your docker-compose.yml currently describes. The release notes say it plainly: “existing containers may be recreated the first time you run compose up after upgrading, as image digests are re-evaluated using the new logic.”
It’s a one-time event, not a recurring problem. But if you weren’t expecting it, a mass container restart looks like an incident. Here’s what actually changed, why it happened once and won’t again, and what else shipped in the same release.
Why Docker Compose Recreates Containers on the First Upgrade Run
Compose decides whether to recreate a container by comparing a hash of its current configuration against what’s already running, and image digests are part of that hash. Version 5.5 changes how those digests get evaluated — more accurately, according to the release notes, which is the whole point of the change. But “more accurate” means containers created under the old evaluation logic look different from what the new logic expects, even if nothing in your compose file actually changed.
So on your first compose up after upgrading, Compose reconciles every service against the new digest logic. Anything that reads as “different” gets recreated once. After that first pass, your containers are baselined against the new logic and stay put on subsequent runs, the same way Compose has always behaved for unchanged services.
The Recurring Complaint Behind the Overhaul
This overhaul didn’t come out of nowhere. Complaints about containers getting recreated on compose up when nothing changed have followed the v2 rewrite from the start. A 2023 GitHub issue documents the pattern exactly: a user changed one service’s image tag, ran compose up -d again with zero further changes, and watched Compose recreate every dependent container anyway — “I did NOT make any changes here, I simply ran compose up again, and again it recreated the containers!”
That specific bug was a v2.16 regression, and Docker fixed it within weeks in v2.17.0. It also involved config-hash comparison generally, not digest reconciliation specifically. But it’s the same category of problem, and it kept resurfacing in new forms: Compose’s decision about whether a container needs recreating didn’t match what a human expected, and each occurrence got a one-off fix. The 5.5 overhaul reads like Docker rebuilding that logic instead of patching around it again.
What Else Shipped in Docker Compose 5.5
The digest change is the headline, but a few other fixes matter if you run Compose in CI or with build-heavy setups.
compose pullnow honorspull_policyrefresh windows —daily,weekly, andevery_Nsettings actually control when Compose re-pulls an image, instead of pulling on every invocation regardless of policy.- Build-only services skip pulling a default image reference they were never going to use, which was previously wasted network time on every
up. - Compose stopped pruning every dangling image in a project on cleanup, a behavior that was too aggressive for anyone sharing base images across services.
- The file watcher now skips unreadable directories instead of failing the entire watch session, and Compose tolerates containers whose image record has gone missing instead of erroring out.
None of these force a workflow change on their own. They’re the kind of fixes you only notice once they stop happening. If you’re still deciding between Compose-managed Docker and a daemonless alternative, the Docker vs Podman comparison is worth reading before you standardize either way.
What to Check Before You Upgrade
- Expect one restart cycle, not zero. If your services hold in-memory state or long-lived connections, plan the first post-upgrade
compose uplike a deploy, not a routine command. - Check
pull_policysettings if you rely on scheduled pulls. The refresh-window fix meansdaily/weekly/every_Nnow actually gate pulls — if you were working around the old always-pull behavior with a wrapper script, that workaround may now be redundant or conflicting. - Run
docker compose config --hash "*"before and after upgrading to see exactly which services Compose considers changed, so the recreation isn’t a surprise mid-deploy. - Don’t run the upgrade for the first time against production. Because the recreation is real, not cosmetic, test it against staging first if your containers have any startup cost or connection-draining behavior worth protecting.
⚠️ Important: if any service uses restart: always alongside a health check with a short grace period, a mass recreation event can trigger cascading restart attempts before dependent services are back up. Stagger the upgrade across environments rather than rolling every host to 5.5 at once. The Docker errors and fixes guide covers what a cascading restart loop looks like if you want to recognize it fast.
Verdict: Should You Upgrade?
Yes, for most setups. The one-time recreation is a known, explained side effect, not a regression, and the underlying fix addresses a category of complaint that’s followed Compose v2 for years. Teams running build-only services or relying on pull_policy refresh windows get a direct, measurable improvement, not just a bug fix.
The exception is anything with strict uptime requirements and no rolling-deploy story for Compose-managed services — for those, schedule the upgrade like you would a dependency bump that touches container lifecycle, with a maintenance window and a rollback plan, rather than pulling 5.5 straight into a production host. If you’re layering Compose on top of a base you’re still learning, the Docker beginner’s guide and the Docker best practices guide are worth a read before you change upgrade habits on production systems.
Frequently Asked Questions
Q: Will Docker Compose keep recreating my containers every time I run compose up?
A: No. The recreation happens once, on your first compose up after upgrading to 5.5, while Compose re-evaluates image digests under the new logic. After that first pass, unchanged services stay running exactly as before.
Q: Do I need to change my docker-compose.yml to avoid the recreation?
A: No changes are required. The recreation is triggered by the new digest evaluation logic itself, not by anything in your compose file. There’s no configuration flag to skip it.
Q: Does the pull_policy refresh window change affect existing daily/weekly settings?
A: It makes them work as documented. Before 5.5, compose pull didn’t reliably respect those refresh windows; now it does, so a pull that was firing more often than intended should slow down to match your configured policy.
Q: Is this related to the old “Compose v2 recreates containers for no reason” complaints?
A: It’s the same category of problem — Compose deciding a container needs recreating when a human wouldn’t expect it — but a different specific mechanism. This overhaul targets digest evaluation, not general config-hash comparison.
Quick Summary
- Docker Compose 5.5 overhauls image digest reconciliation, and existing containers get recreated once on the first
compose upafter upgrading - After that first pass, Compose behaves normally — unchanged services stay running on subsequent runs
compose pullnow actually honorspull_policyrefresh windows (daily,weekly,every_N), which previously didn’t reliably apply- Build-only services no longer pull an unused default image reference, and Compose no longer prunes every dangling image in a project on cleanup
- Test the upgrade in staging first if any service has real startup cost, in-memory state, or strict health-check timing
Run docker compose config --hash "*" before you upgrade so you know in advance which services Compose considers changed. Docker Compose recreates containers exactly once during this transition, and treating that first post-upgrade compose up like a deploy rather than a routine command is the difference between a known side effect and an incident.