docker compose pulls from a registry although the image exists locally
docker compose up tries to pull an image that was built on this machineShort 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.
Fix it fast
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:"2Match what you see, then jump to its fix
- 1
docker image ls shows the image, with another tag or repository nameThe name or tag in the compose file differs from the built imageFix - 2
The 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
The 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
- 1
What does the error look like?
docker compose up tries to pull an image that was built on this machineThe 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-app2Fix
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:latest3Verify
Start the stack.
docker compose up -dConfirmed by docs.docker.com
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 ls2Fix
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-appConfirmed by docs.docker.com
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_policy2Fix
Set pull_policy: never on that service.
services:
app:
image: my-app:latest
pull_policy: never3Verify
Start the stack.
docker compose up -dConfirmed by docs.docker.com
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
Servers
docker pull says access denied or repository does not exist
Error response from daemon: pull access denied for <image>
Docker prints this when it cannot find the image under that name with your current credentials.
3 causes, each with a fixServers
apk cannot find py-pip in an Alpine Docker image
py-pip (no such package):
On current Alpine releases there is no package called py-pip.
2 causes, each with a fixServers
ng serve runs in the container but localhost:4200 does not open
The browser cannot open localhost:4200 although ng serve is running in the container
ng serve listens on localhost by default, which inside a container is the container itself.
3 causes, each with a fixServers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
AH00558: Apache in Docker cannot reliably determine its fully qualified domain name
Set the 'ServerName' directive globally to suppress this message
AH00558 is a warning, not a crash.
2 causes, each with a fixServers
Apache in a Docker container logs AH01114 when it proxies to a backend
AH01114: HTTP: failed to make connection to backend: api
Apache's proxy worker could not open a connection to the address in ProxyPass.
5 causes, each with a fix