A Docker host keeps running the old image after you pushed a patched rebuild to the same tag — why?

## Two separate things called "the image" A registry reference like `recon-worker:4.7.3` is a name. What actually runs is a specific image, identified by a content digest, and a container is bound to the image **ID** it was created from — not to the name you typed. Rebuilding and pushing under the same tag changes what the name means in the registry and changes nothing about the images already on your hosts or the containers already created from them. ## Why each command leaves you on the old bytes - `docker run recon-worker:4.7.3` uses the default pull policy `missing`: it consults the registry only when no local image matches the reference. The host pulled 4.7.3 eleven days ago, so it runs those bytes. - `docker restart <container>` stops and starts the **same container object**, whose root filesystem and image ID were fixed at creation. It cannot pick up a new image; neither can a `--restart` policy firing after a crash or a host reboot. - `docker compose up -d` recreates a service only when its configuration has changed. If the compose file still says the same image reference and Compose sees a local image for it, it can legitimately leave the running container alone. The result is a fleet that quietly splits: hosts provisioned after the push run the patched image, hosts provisioned before it run the vulnerable one, and both report the same tag in `docker ps`. On a payments reconciliation batch this is the worst kind of drift, because the two populations differ only in the base layers and behave identically until something audits them. ## Making the rebuild land Pull, then recreate: ```bash docker pull recon-worker:4.7.3 docker rm -f recon-worker && docker run -d --name recon-worker recon-worker:4.7.3 ``` Or force the policy at run time with `docker run --pull always`. With Compose, `docker compose pull && docker compose up -d` fetches the new bytes and recreates the services whose image ID changed; add `--force-recreate` when you want the recreation to happen regardless. The rule to internalise: **pull refreshes the image, recreate refreshes the container, restart refreshes neither.** ## Verify, do not assume On a host, `docker image inspect --format '{{index .RepoDigests 0}}' recon-worker:4.7.3` shows the registry digest those local bytes came from; compare it to what the build published. To check what a *running* container is actually on, `docker inspect --format '{{.Image}}' recon-worker` gives the image ID it was created from — if that ID is not the ID of the freshly pulled image, the container is old no matter what its tag says. This is the check that turns "we rolled out the patch" into evidence. After a same-tag replacement the previous image loses its name and shows up as `<none>` in `docker image ls`. It is still on disk, still referenced by any container created from it, and worth reclaiming with `docker image prune` once nothing runs on it — a fleet that pulls a roughly 2.3 GB image weekly and never prunes fills its disks on schedule. ## The structural fix Every step above is a workaround for having deployed a mutable name. If each build publishes a unique, immutable reference — `recon-worker:4.7.3-b2183`, or better the digest `recon-worker@sha256:...` — then "same tag, different bytes" cannot happen: changing what runs is a change to the reference, which is visible in a diff, reviewable, and trivially auditable across a fleet. Deployment systems that reconcile a declared reference against what is running make the pull-and-recreate cycle automatic, but they inherit the same rule: an immutable reference is what makes the intent unambiguous, and a mutable tag is what makes a rollout unverifiable. One more habit is worth naming: a patched rebuild is a deployment, with the same testing and staged rollout as any other. The base changed underneath a C++ daemon that links against the runtime shared libraries in it — a refreshed base is not a no-op just because your source did not change.