Most of the time, docker compose up does exactly what I want.
If I change an environment variable or tweak my Compose file, I rerun it and Docker Compose recreates the container. Simple.
This time was different. I was building the image somewhere else, publishing it to a registry, and expecting Compose to pull the newest version when I ran docker compose up again. It did recreate the container, but it kept using the image I already had locally.
That sent me down a small rabbit hole until I found the missing piece: pull_policy.
By default, Compose does not always pull a fresh image before starting your services.
If the image already exists locally, Compose will usually keep using that cached copy. That is great when you build locally or want faster startup times, but not so great when the image is produced elsewhere and reused with the same tag.
In other words, docker compose up recreating a container does not automatically mean it will fetch a newer image from the registry first.
pull_policyCompose lets you control this behavior per service with pull_policy.
If you always want the newest image from the registry, set it to always:
services:
app:
image: ghcr.io/your-org/your-app:main
pull_policy: alwaysAfter adding that, rerunning docker compose up pulls the image again before starting the container.
That was exactly what I needed.
This is especially handy when:
docker compose up to behave more like "use the latest remote image" than "reuse whatever is already cached locally"If you only need this occasionally, you can also do it as a one-off from the command line:
docker compose up --pull alwaysBut if this is your normal workflow, putting pull_policy: always in the Compose file is nicer because you do not have to remember the flag every time.