Maaz Zindani

Loading the index…

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

docker buildx build finishes, but the image is not in docker images

Errordocker buildx build ends without an error

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

  • Applies to Docker Engine 28, Docker Buildx 0.2x, Docker Desktop 4
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 ls
  2. 2Match what you see, then jump to its fix

    1. 1docker 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. 2The 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. 3The build has --platform with two or more values, for example linux/amd64,linux/arm64, plus --load.A multi-platform build cannot be loadedFix

What does the error look like?

  • docker buildx build ends without an error
  • docker image ls does not show the new image
  • docker 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 ls

2Fix

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-app

Confirmed by docs.docker.com

Did this fix it?

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/*.yml

2Fix

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-app

Confirmed by docs.docker.com

Did this fix it?

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-app

Confirmed by docs.docker.com

Did this fix it?

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

Next step

Want this handled for good?

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