Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

docker compose pulls from a registry although the image exists locally

Errordocker compose up tries to pull an image that was built on this machine

Short answer

Compose looks for the exact image name and tag from your file in the local image store, and pulls when it is missing. Compare the name with docker image ls. If the image was built with a builder that does not load results, rebuild with --load. For images that exist only locally, set pull_policy: never.

  • Applies to Docker Engine 28, Docker Compose v2, Docker Buildx
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List the local images and compare name and tag with the image value in the compose file, character by character.

    docker image ls
    docker compose config | grep -n "image:"
  2. 2Match what you see, then jump to its fix

    1. 1docker image ls shows the image, with another tag or repository nameThe name or tag in the compose file differs from the built imageFix
    2. 2The build finished with no error, and docker image ls does not list the imageThe image was built with a builder that does not load it into the local storeFix
    3. 3The image is listed under the right name, and Compose still contacts a registryCompose is allowed to pull, and the image exists only on this machineFix

What does the error look like?

  • docker compose up tries to pull an image that was built on this machine
  • The pull fails for a name that exists only locally

Cause 1 of 3

The name or tag in the compose file differs from the built image

1Check

The image value is registry, project, image name and tag. A missing tag means latest. my-app:1.0 and my-app are different images.

docker image ls my-app

2Fix

Tag the image with the exact name the file uses, or change the file to the built name.

docker tag my-app:1.0 my-app:latest

3Verify

Start the stack.

docker compose up -d

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

The image was built with a builder that does not load it into the local store

1Check

With the docker-container driver, the build result stays in the build cache unless you ask for it to be loaded.

docker buildx ls

2Fix

Build with --load, or use the docker driver's builder.

docker buildx build --load -t my-app:latest .

3Verify

The image is listed now.

docker image ls my-app

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

Compose is allowed to pull, and the image exists only on this machine

1Check

With no pull_policy set, Compose pulls when the image is not found in the platform cache. The value never makes it rely on the local copy, and report a failure if none exists.

docker compose config | grep -n -i pull_policy

2Fix

Set pull_policy: never on that service.

services:
  app:
    image: my-app:latest
    pull_policy: never

3Verify

Start the stack.

docker compose up -d

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Use explicit tags, not an implicit latest.
  • If one file builds and runs, give the service a build section so Compose can build it.
  • Always add --load when building with a docker-container builder.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.