BuildKit Garbage Collection: Policies and Configuration

--- title: Build garbage collection description: Learn about garbage collection in the BuildKit daemon keywords: build, buildx, buildkit, garbage collection, prune, gc aliases: - /build/building/cache/garbage-collection/ --- While [`docker builder prune`](/reference/cli/docker/builder/prune.md) or [`docker buildx prune`](/reference/cli/docker/buildx/prune.md) commands run at once, Garbage Collection (GC) runs periodically and follows an ordered list of prune policies. The BuildKit daemon clears the build cache when the cache size becomes too big, or when the cache age expires. For most users, the default GC behavior is sufficient and doesn't require any intervention. Advanced users, particularly those working with large-scale builds, self-managed builders, or constrained storage environments, might benefit from customizing these settings to better align with their workflow needs. The following sections explain how GC works and provide guidance on tailoring its behavior through custom configuration. ## Garbage collection policies GC policies define a set of rules that determine how the build cache is managed and cleaned up. These policies include criteria for when to remove cache entries, such as the age of the cache, the amount of space being used, and the type of cache records to prune. Each GC policy is evaluated in sequence, starting with the most specific criteria, and proceeds to broader rules if previous policies do not free up enough cache. This lets BuildKit prioritize cache entries, preserving the most valuable cache while ensuring the system maintains performance and availability. For example, say you have the following GC policies: 1. Find "stale" cache records that haven't been used in the past 48 hours, and delete records until there's maximum 5GB of "stale" cache left. 2. If the build cache size exceeds 10GB, delete records until the total cache size is no more than 10GB. The first rule is more specific, prioritizing stale cache records and setting a lower limit for a less valuable type of cache. The second rule imposes a higher hard limit that applies to any type of cache records. With these policies, if you have 11GB worth of build cache, where: - 7GB of which is "stale" cache - 4GB is other, more valuable cache A GC sweep would delete 5GB of stale cache as part of the 1st policy, with a remainder of 6GB, meaning the 2nd policy does not need to clear any more cache. The default GC policies are (approximately): 1. Remove cache that can be easily regenerated, such as build contexts from local directories or remote Git repositories, and cache mounts, if hasn't been used for more than 48 hours. 2. Remove cache that hasn't been used in a build for more than 60 days. 3. Remove unshared cache that exceeds the build cache size limit. Unshared cache records refers to layer blobs that are not used by other resources (typically, as image layers). 4. Remove any build cache that exceeds the build cache size limit. The precise algorithm and the means of configuring the policies differ slightly depending on what kind of builder you're using. Refer to [Configuration](#configuration) for more details. ## Configuration > [!NOTE] > If you're satisfied with the default garbage collection behavior and don't > need to fine-tune its settings, you can skip this section. Default > configurations work well for most use cases and require no additional setup. Depending on the type of [build driver](../builders/drivers/_index.md) you use, you will use different configuration files to change the builder's GC settings: - If you use the default builder for Docker Engine (the `docker` driver), use the [Docker daemon configuration file](#docker-daemon-configuration-file). - If you use a custom builder, use a [BuildKit configuration file](#buildkit-configuration-file). ### Docker daemon configuration file If you're using the default [`docker` driver](../builders/drivers/docker.md), GC is configured in the [`daemon.json` configuration file](/reference/cli/dockerd.md#daemon-configuration-file),

This document explains how BuildKit's garbage collection (GC) works, including its policies for managing build cache and how to configure it. GC runs periodically to clear the build cache based on factors like cache age and size. The document details the default GC policies, emphasizing how they prioritize cache entries, and provides instructions for customizing these settings using either the Docker daemon configuration file or a BuildKit configuration file, depending on the build driver being used.