Build Docker Images and Reclaim Build Cache with docker builder

You will build a Docker image from a local context, confirm that the image exists, and remove selected build cache when disk usage grows. The commands target the Docker CLI installed here, Docker CE CLI 29.8.1 with Buildx 0.37.1. Allow 10 to 20 minutes for a first build, depending on the base image and network speed.

The command group is docker builder. Its top-level manual page is brief: the useful operational detail is in docker-builder-build(1) and docker-builder-prune(1). On this installation, the builder commands are backed by Buildx, so docker builder --help may show more current options than the generated manpage.

1. Check Docker access

Run this as your normal account from a shell. You need the Docker CLI, a running Docker daemon or another configured builder, and permission to use it. A working Docker installation normally lets you run the version check without elevated privileges.

$ command -v docker
/usr/bin/docker
$ docker version --format '{{.Client.Version}}'
29.8.1
$ docker builder --help
Usage:  docker buildx [OPTIONS] COMMAND

If the version command fails with a daemon or permission error, fix that environment first. Do not add sudo automatically: membership of the Docker group grants powerful control over the host. If your site deliberately requires root for Docker access, use the local administrator's procedure and understand that the build then runs with that account's permissions.

2. Check the build context

Change to a project directory containing the files needed by the build. The final argument to docker builder build is the build context, and . means the current directory. By default the Dockerfile is expected at PATH/Dockerfile.

$ cd /path/to/your/project
$ test -f Dockerfile && echo 'Dockerfile found'
Dockerfile found
$ docker builder build --help
Usage:  docker buildx build [OPTIONS] PATH | URL | -

Replace /path/to/your/project with a real directory. Keep the context narrow. Docker sends context files to the builder, so a context of / or a home directory can be slow and can expose files that the build does not need. Use a suitable .dockerignore file for generated output, credentials and large archives.

3. Build and tag the image

Build the image with a local tag. This changes builder state and may download a base image, but it does not publish the result to a registry. The build may execute commands from the Dockerfile, so read that file before running an unfamiliar project.

$ docker builder build --tag example/widget:dev .
[+] Building 12.4s (8/8) FINISHED
 => exporting to image
 => => naming to docker.io/library/example/widget:dev

The progress layout varies with the terminal and Dockerfile. A successful command exits with status zero and normally leaves an image tagged example/widget:dev. The tag is only a local example; use the repository and tag that your project specifies.

4. Verify the result

Check the tag and image ID rather than relying only on the progress display. This is an ordinary read-only command.

$ docker image inspect example/widget:dev --format '{{.Id}}'
sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
$ docker image inspect example/widget:dev --format '{{.RepoTags}}'
[example/widget:dev]

Your image ID will be different. If inspection says that the image does not exist, check the tag spelling and read the build's final error. A successful build can also be tested with the project's normal docker run command, but do not start a service or expose a port unless you intend to do so.

5. Use another Dockerfile or a clean build

Pass --file when the Dockerfile has a different name or location. The context remains the final argument, so keep both paths visible when reviewing a script.

$ docker builder build \
    --file docker/Dockerfile.release \
    --tag example/widget:release \
    .

The local command also supports --no-cache to ignore previously stored build cache and --pull to always attempt to fetch newer referenced base images. Those options can make a build slower and can change which external content it uses. Use them deliberately when debugging stale layers or refreshing a base image, not as a routine first response to every failure.

For easier-to-read CI logs, add --progress=plain. For a build that should only check the Dockerfile without producing the normal image result, the installed CLI advertises --check; confirm the option with docker builder build --help on the target host before putting it in a portable script.

6. Inspect cache before removing it

Build cache speeds up later builds but consumes disk space. Inspect the selected builder before deleting anything:

$ docker builder du
ID                         RECLAIMABLE   SIZE      LAST ACCESSED
local-cache                 true          412.3MB   2 days ago

The exact table depends on your builder and cache. If docker builder du is not available in an older installation, use docker builder --help to check the commands exposed there. Cache is not the same thing as your tagged image: pruning cache is generally less disruptive than removing an image, but it can make the next build download and execute more work.

7. Prune only cache you have chosen

Pruning is destructive to the selected cache records. It does not have an undo command, so do not use --force in a script until the filter has been checked interactively. Start with a time filter that preserves recently used records:

$ docker builder prune --filter 'until=168h'
WARNING! This will remove all dangling build cache. Are you sure you want to continue? [y/N] y
Deleted build cache objects:
abc123

Total reclaimed space: 412.3MB

Use --force only when the scope is already understood:

$ docker builder prune --force --filter 'until=168h'

The installed manpage documents --all for removing all unused build cache rather than only dangling cache. Treat it as a wider deletion and inspect docker builder prune --help first, because cache option names and resource controls vary between Docker releases. If you remove useful cache accidentally, the recovery is to run the build again; Docker reconstructs cache as layers are rebuilt, but the lost time and downloads cannot be undone.

Common failure traps

• Wrong context: docker builder build -f docker/Dockerfile . reads the Dockerfile from docker/ but still sends the current directory as context. A context outside the intended project can include secrets or make the transfer unexpectedly large.
• Unexpected rebuilds: --no-cache disables reuse, while a changed build argument, source file or base image can invalidate later layers. Check the progress output before deleting cache.
• Missing output: a build may complete without loading an image into the local Docker image store when a non-default output is selected. Verify with docker image inspect and read the output options shown by the installed help.
• Permission errors: changing the command to sudo docker ... can select a different configuration, credentials and builder. Resolve the intended account and builder instead.