docker buildx build finishes, but the image is not in docker images
docker buildx build ends without an errorShort answer
A buildx build only lands in your local image list when its output is the local image store. With the docker-container driver the result stays in the build cache unless you add --load, and a different --output type or a multi-platform build also keeps it out. Check the builder driver first, then set the output.
Fix it fast
1Find out which cause you have
List the builders and look at the driver of the one that is in use (the name with a star). The docker driver loads results automatically; the others do not.
docker buildx ls2Match what you see, then jump to its fix
- 1
docker buildx ls shows the current builder with the docker-container driver, and the build command has no --load or --output flag.The builder uses the docker-container driver and the build has no --loadFix - 2
The command has --output type=image, type=local, type=tar or type=oci, or --push, and the image is in a registry, a folder or a tar file instead.A different --output type sends the result somewhere elseFix - 3
The build has --platform with two or more values, for example linux/amd64,linux/arm64, plus --load.A multi-platform build cannot be loadedFix
- 1
What does the error look like?
docker buildx build ends without an errordocker image ls does not show the new imagedocker run cannot find the image you just built
Cause 1 of 3
The builder uses the docker-container driver and the build has no --load
1Check
The docker driver loads the result into the local image store by itself. The docker-container, kubernetes and remote drivers do not; without an output option the result stays in the build cache.
docker buildx ls2Fix
Add --load to the build command. It is shorthand for --output=type=docker and loads a single-platform result into docker images.
docker buildx build --load -t my-app:latest .3Verify
The image is listed.
docker image ls my-appConfirmed by docs.docker.com
Cause 2 of 3
A different --output type sends the result somewhere else
1Check
Only the docker output type, without a dest, loads into the local store. Docker's reference says --push means type=registry, and a custom output replaces loading.
grep -n -- "--output\|--push\|-o " Makefile build.sh .github/workflows/*.yml2Fix
For a local image use --load or --output type=docker. If you need both a pushed image and a local one, run two builds.
docker buildx build --push -t registry.example.com/my-app:1.0 .
docker buildx build --load -t my-app:1.0 .3Verify
Check the local list.
docker image ls my-appConfirmed by docs.docker.com
Cause 3 of 3
A multi-platform build cannot be loaded
1Check
Docker's reference says the default image store of Docker Engine does not support loading multi-platform images. --load loads only a single-platform result.
docker buildx build --platform linux/amd64,linux/arm64 -t my-app:latest .2Fix
Load one platform at a time for local use, and push the multi-platform build straight to a registry. Docker also names the containerd image store as a way to hold multi-platform images locally.
docker buildx build --platform linux/amd64 --load -t my-app:amd64 .
docker buildx build --platform linux/amd64,linux/arm64 --push -t registry.example.com/my-app:1.0 .3Verify
The single-platform tag is listed locally.
docker image ls my-appConfirmed by docs.docker.com
How do I stop it coming back?
- Write --load or --push explicitly in every buildx command, so the destination is never left to the driver.
- Run docker buildx ls once on a new machine or CI runner to see which driver is the default there.
- Use a separate tag for each platform you load locally.
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 warns that the image platform linux/amd64 does not match the arm64 host
The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8)
The image was built for linux/amd64 and your machine is arm64, such as an Apple Silicon Mac.
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