Skip to main contentClaim $5 in free credit — one-time, per account. Claim $5 free
Krova CloudKrova Cloud
CI/CD & DevOps

Docker Build Cache Cleanup: Choose the Right Builder

Find the Docker builder that owns your CI cache, inspect reclaimable and shared records, and choose a narrow cleanup you can verify.

RB
Rohit Bhadani5 min read
Share
Conceptual frosted-glass builder and cache tiles, with the headline Clean the Right Build Cache.

Suppose an image build finishes successfully on your persistent CI runner, but the next job runs short of disk space. You remove an old image and barely move the free-space figure. The build worked; the storage story is still unfinished. For Docker build cache cleanup, identify the builder and its storage location first, inspect its cache, then choose a narrow removal policy.

This is a hypothetical situation for a self-managed runner, including one you operate on Cube. The commands are guidance checked against Docker’s documentation; they were not executed for this article. You’ll need authorized Docker and Buildx access. No recovered-space figure or production build result is claimed.

Find the builder before cleaning

Start by finding the builder used by the failing job, rather than assuming your interactive shell targets the same one:

docker buildx ls

The Buildx listing reference shows builder names, nodes, drivers and endpoints; an asterisk marks the selected builder. Compare that information with the job’s build command and environment. A runner can talk to a builder elsewhere, so a full disk on the runner and a large remote cache are not automatically the same problem.

Docker’s builder overview distinguishes the default daemon-backed builder from dedicated container, Kubernetes and remote builders. It also documents selection through --builder and BUILDX_BUILDER. Record the builder name and endpoint with the failed job. If the job explicitly selects a builder, use that selection for the investigation.

Now name the builder explicitly in the inspection. ci-builder is a placeholder: replace it with the verified name from your environment.

builder='ci-builder'
docker buildx --builder "$builder" du --verbose

The Buildx disk-usage reference describes reclaimable, shared and mutable records. A record marked non-reclaimable is actively in use. Shared storage may also be needed by an image, so removing its cache record can remove metadata while leaving the underlying layers in place. Don’t translate the displayed cache total into a promise of equally large filesystem savings.

Keep two observations beside each other: the builder’s cache report and available space on the filesystem backing that builder. If you’re connected to another machine, inspect the relevant filesystem there with the appropriate access. If the failure concerns another mount or exhausted inodes, follow the filesystem and inode diagnosis instead of widening a cache cleanup.

Choose what you can afford to rebuild

For the hypothetical runner, the next decision is about what you can afford to rebuild. Recent cache might be useful for the next branch build; older cache might be expendable. Confirm that required source, base images and dependencies remain available before discarding a useful local copy. Cache is a performance aid, not a substitute for retaining the inputs and outputs your pipeline requires.

An age filter gives that decision a concrete scope. The following inspection limits the report to records matching a seven-day last-use threshold. The value is illustrative, not a recommended retention period for every runner:

docker buildx --builder "$builder" du --filter 'until=168h'

This is an inspection, not a transactional dry run. Another build can change the cache between inspection and removal. Arrange an appropriate maintenance window or pause new work on this builder, preserve any evidence you need, and review the impact with the runner’s owner before running the removal command below.

Docker’s prune reference says the command clears cache for the selected builder. Its until filter preserves records used within the specified duration. For this example, the same verified builder and threshold are carried into the cleanup; the command removes eligible cache and can make later builds repeat work.

docker buildx --builder "$builder" prune --filter 'until=168h'

Keep the confirmation prompt and read it. This example deliberately leaves out --force and --all; it doesn’t call for a broad system or volume prune. Check your installed Buildx version’s help before adopting a runbook, and don’t delete BuildKit-managed storage directories by hand to imitate the command.

After an authorized cleanup, repeat the unfiltered cache inspection for the same builder and check free space on the same backing filesystem. Then run a representative build and compare its result and duration with your baseline. If little space returned, revisit shared records, in-use cache and other storage consumers. If the next build slowed down, include that cost in the retention decision rather than treating cleanup as an unconditional improvement.

Turn repeat cleanups into a policy

A recurring problem needs a policy, not a larger collection of emergency commands. Docker’s garbage-collection guide describes periodic, ordered cache policies and explains that configuration differs between the Docker driver and custom builders. Read the configuration for the builder you actually run; a daemon setting on one host doesn’t establish a policy for a different BuildKit service.

If you replace runners between jobs, separate local cache lifecycle from exported cache. Docker’s cache-backend guide describes BuildKit’s internal cache and optional external exports. Inventory both. Cleaning one builder is not a retention policy for a registry cache, and an external cache is not proof that every local record can be reproduced.

For a persistent CI runner on Cube, keeping tools and cache warm can be useful, but you still own their lifecycle. Finish this investigation with a short note: builder and endpoint, backing filesystem, inspection time, removal scope, free space afterward, and the next build’s outcome. That note makes the next cleanup a decision you can explain.

Creation context: this AI-assisted guide uses the linked primary documentation. The runner scenario is hypothetical, no Docker cleanup or workload benchmark was performed, and the cover is a generated conceptual illustration.

Plan your CI runner on Cube

Explore a Linux microVM you control, and make cache ownership and retention part of your runner’s operating plan.

For AI agents:llms.txtsitemap

Related posts