Build and Verify a Docker Image with docker builder build

A build that finishes without error is not proof you got the image you wanted, so docker builder build deserves a proper check afterwards. Here you build a small, tagged image from a local Dockerfile, confirm it actually landed in your local store, and run it once. The command is an alias for the Buildx build path on the installed Docker CLI, but this guide uses the documented docker builder build form.

Allow about 10 minutes for a first build, including downloading the base image. You need Docker CLI access to a working Docker daemon or builder, a text editor, and a directory whose contents you are happy to send as build context. Ordinary Docker commands are enough when your account can access the Docker socket. If this installation requires elevated access, prefix only the Docker commands with sudo; do not make the Dockerfile or its output world-writable.

1. Check the installed command

Start by recording the local client and builder details. This guide was checked with Docker CE CLI 29.8.1 and Buildx 0.37.1. Your output can differ, and the active builder controls where the build runs.

$ docker version --format '{{.Client.Version}}'
29.8.1
$ docker buildx version
github.com/docker/buildx v0.37.1 ...
$ docker buildx inspect --bootstrap
Name: default
Driver: docker
...

Checkpoint: the version command prints a client version and inspect shows a builder. If the daemon is unreachable, fix the Docker context or service before changing build flags. A build cannot succeed without a usable builder.

2. Prepare a small, explicit build context

A context is the directory, URL or standard input named by the final argument. With a local directory, Docker processes that directory recursively, so an accidental context such as a home directory can expose far more data to the builder than intended. Create a dedicated directory and exclude local clutter with a .dockerignore file.

$ mkdir -p ~/docker-demo
$ cd ~/docker-demo
$ printf '%s\n' 'FROM alpine:3.20' 'CMD ["sh", "-c", "printf '\''builder-ok\\n'\''"]' > Dockerfile
$ printf '%s\n' '.git' '*.env' '*.key' '*.pem' 'tmp/' > .dockerignore
$ sed -n '1,5p' Dockerfile
FROM alpine:3.20
CMD ["sh", "-c", "printf 'builder-ok\\n'"]

The final positional argument will be ., meaning this directory. Do not put passwords, private keys or unrelated source trees in it. A .dockerignore reduces accidental transfer, but it is not a substitute for checking what the Dockerfile copies.

3. Build and tag the image

Run the build from the context directory. The --tag option gives the result a name and optional tag. Without --file, the command looks for PATH/Dockerfile, so the default file works here.

$ docker builder build --tag docker-demo:1.0 .
[+] Building ...
 => exporting to image
 => => naming to docker.io/library/docker-demo:1.0
 => => unpacking to docker.io/library/docker-demo:1.0
The final line reports the completed image export.

The progress display varies by terminal and builder. A successful build exits with status zero. With the Docker driver used in this check, the single-platform result is available to the local image store. The first run may pull alpine:3.20; later runs can reuse cached steps.

Checkpoint: if you see a failure, read the first failing Dockerfile instruction. Common causes are a missing file outside the context, a misspelled tag, no network access to the base image, or a builder that cannot execute the requested platform.

4. Verify the tag and run the image

Do not treat a clean-looking progress log as proof that the expected tag exists. Ask the image store, then run the harmless command defined by the Dockerfile.

$ docker image inspect docker-demo:1.0 --format '{{.Id}}'
sha256:...
$ docker run --rm docker-demo:1.0
builder-ok

docker run --rm removes the short-lived container when it exits. It does not remove the image. To see the image and its size, use:

$ docker image ls docker-demo
REPOSITORY   TAG   IMAGE ID       CREATED          SIZE
docker-demo  1.0   ...            ...              ...

5. Control the Dockerfile and cache deliberately

For a Dockerfile with another name or location, use --file while keeping the context as the final argument. The file path and context are separate: the Dockerfile can be elsewhere, but COPY and ADD still read from the context.

$ docker builder build \
    --file docker/production.Dockerfile \
    --tag example/app:2026-09 \
    .

Use --no-cache when you need every eligible step rebuilt, for example after checking that a dependency download is genuinely fresh. Use --pull when you want Docker to attempt to retrieve newer versions of referenced base images. These options can make a build slower and can change the resulting image, so record them in repeatable build scripts rather than adding them by reflex.

$ docker builder build --pull --no-cache --tag docker-demo:checked .

Build arguments are supplied with repeated --build-arg NAME=value options, but they are not a safe place for passwords: values may be visible in build metadata or history depending on how the Dockerfile uses them. Use a supported secret mount mechanism in a BuildKit-aware Dockerfile for credentials, and keep secrets out of the context.

6. Use stages and platforms with a clear boundary

For a multi-stage Dockerfile, --target stops at a named build stage. This is useful for testing or inspecting an intermediate result without silently changing the production target in the Dockerfile.

$ docker builder build \
    --target test \
    --tag example/app:test \
    .

--platform selects a target such as linux/amd64 or linux/arm64. Cross-platform RUN instructions need suitable builder and runtime support, so inspect the builder before requesting a different architecture. A successful transfer to another machine is not proof that native execution will work there.

7. Diagnose without destroying useful state

Use --quiet when a script needs only the image ID on success. Use --iidfile to write the built image ID to a file that you control. Keep that file outside sensitive directories and remove it when its consumer has finished.

$ docker builder build --quiet --iidfile /tmp/docker-demo.iid --tag docker-demo:1.0 .
sha256:...
$ test -s /tmp/docker-demo.iid && docker image inspect "$(cat /tmp/docker-demo.iid)" --format '{{.RepoTags}}'
[docker-demo:1.0]

The build cache and intermediate containers are state. Do not add --force-rm or prune commands as a blind repair: the former changes cleanup behaviour, while cache removal affects future build speed. If you do need to reclaim cache later, inspect it first with the relevant builder usage command and remove only data you no longer need.

Done means