Docker Compose won't pull the latest image unless you tell it to

docker compose up recreates a container when your config changes, but it does not always pull the latest image first. If the tag already exists locally, Compose reuses the cached copy.

I hit this while building the image in CI, publishing it to a registry, and expecting Compose to fetch the newest version on the next docker compose up. It recreated the container and kept running the old local image. The missing piece was pull_policy.

Compose reuses the cached image instead of checking the registry

By default, Compose does not pull a fresh image before starting your services.

If the image already exists locally, Compose keeps using that cached copy. That is fine when you build locally or want faster startup times. It is wrong when the image is produced elsewhere and republished under the same tag.

In other words, docker compose up recreating a container does not mean Compose will pull a new image from the registry first.

Set pull_policy: always to make Docker Compose pull the latest image

Docker Compose exposes this as pull_policy, set per service in the Compose file.

To make Docker Compose always pull the latest image from the registry, set it to always:

services:
  app:
    image: ghcr.io/your-org/your-app:main
    pull_policy: always

After adding that, rerunning docker compose up pulls the image again before starting the container.

always is one of four values. missing is the default and pulls only when the image is absent locally. never fails instead of pulling, which is what you want for offline or air-gapped runs. build rebuilds from the Dockerfile. The docs list all of them in the Compose file reference.

Use it when the image is built somewhere other than your machine

This is especially handy when:

• the image is built in CI instead of on your machine
• you publish a new image under the same tag
• you want docker compose up to behave more like "use the latest remote image" than "reuse whatever is already cached locally"

If you only need to force a pull occasionally, do it as a one-off from the command line:

docker compose up --pull always

But 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.