How to use docker buildx du command to check disk usage

Introduction

In this lab, you will learn how to effectively use the docker buildx du command to inspect and understand the disk usage of your Docker build cache. You will begin by checking the basic disk usage for your current builder and understanding the meaning of the output columns, including CACHE ID, SIZE, and LAST ACCESSED.

Furthermore, you will explore how to use verbose output to gain more detailed insights into individual cache records and learn how to check the disk usage for a specific builder instance, allowing you to manage and optimize your build cache more effectively.

Skills Graph

Show disk usage for the current builder

In this step, you will learn how to check the disk usage of your current Docker builder. The docker buildx du command is used to display the disk usage of build cache. This is useful for understanding how much space your build cache is consuming and for identifying potential areas for cleanup.

First, let's execute the docker buildx du command without any options to see the basic disk usage information for the current builder.

docker buildx du

You should see output similar to this, showing the total size of the build cache. The exact size will vary depending on your previous build activities.

CACHE ID                                    SIZE      LAST ACCESSED
... (output will vary)
TOTAL: 123.4MB

The output shows a list of cache entries with their ID, size, and last accessed time. The TOTAL line at the end indicates the total disk space used by the build cache for the current builder.

Understand the output of docker buildx du

In the previous step, you executed the docker buildx du command and saw output showing cache entries and a total size. In this step, we will delve deeper into understanding the different columns in the output.

Let's look at the output again:

CACHE ID                                    SIZE      LAST ACCESSED
... (output will vary)
TOTAL: 123.4MB

• CACHE ID: This is a unique identifier for each cache entry. These IDs are generated by BuildKit and represent different layers or stages in your build process that have been cached.
• SIZE: This column shows the size of the specific cache entry. This is the amount of disk space that this particular cached layer or stage is consuming.
• LAST ACCESSED: This indicates the last time this cache entry was used during a build. This information is helpful for identifying cache entries that are no longer actively being used and could potentially be pruned to free up space.

The TOTAL line at the bottom provides the sum of the sizes of all the cache entries listed, giving you the overall disk usage of the build cache for the current builder. Understanding these columns helps you analyze your build cache and manage its size effectively.

Use verbose output to inspect disk usage records

In this step, you will learn how to get more detailed information about the build cache entries by using the verbose output option with the docker buildx du command. The verbose output provides additional details that can be helpful for debugging and understanding the origin of cached layers.

To get verbose output, use the -v or --verbose flag with the docker buildx du command:

docker buildx du -v

The output will now include more columns, such as USAGE, DESCRIPTION, and potentially others depending on the cache entry type.

CACHE ID                                    SIZE      LAST ACCESSED   USAGE     DESCRIPTION
... (output will vary)
TOTAL: 123.4MB

• USAGE: This column might provide information about how the cache entry is being used or referenced.
• DESCRIPTION: This column often contains a description of the build step or instruction that generated this cache entry. This is very useful for identifying which parts of your Dockerfile or build process are contributing to the cache size.

By examining the DESCRIPTION column in the verbose output, you can see which specific build instructions (like RUN, COPY, etc.) correspond to each cache entry. This helps you understand the structure of your build cache and pinpoint areas where you might be able to optimize your Dockerfile to reduce cache size.

Check disk usage for a specific builder instance

In this step, you will learn how to check the disk usage for a specific Docker builder instance. By default, docker buildx du shows the disk usage for the currently active builder. However, you might have multiple builder instances configured, and you may want to inspect the cache usage for a different one.

First, let's list the available builder instances to identify the one you want to inspect. You can do this using the docker buildx ls command:

docker buildx ls

The output will show a list of your builder instances. Look for the NAME column to identify the name of the builder you are interested in. The currently active builder will be marked with an asterisk (*).

NAME/NODE       DRIVER/ENDPOINT             STATUS   BUILDKIT             PLATFORMS
default *       docker                      running  v0.10.5+a34f333b1f   linux/amd64, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/arm/v7, linux/arm/v6
mybuilder       docker-container            running  v0.10.5+a34f333b1f   linux/amd64, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/arm/v7, linux/arm/v6

Now, to check the disk usage for a specific builder instance, you can use the --builder flag followed by the name of the builder. For example, if you have a builder named mybuilder, you would run:

docker buildx du --builder mybuilder

Replace mybuilder with the actual name of the builder instance you want to inspect. This command will display the disk usage specifically for the cache associated with that builder instance. This is useful if you are working with different builder configurations or if you want to isolate the cache usage of a particular build environment.

Summary

In this lab, you learned how to use the docker buildx du command to check the disk usage of your Docker build cache. You started by executing the basic command to see the total size and a list of cache entries.

You then gained a deeper understanding of the output columns, including CACHE ID, SIZE, and LAST ACCESSED, which provide details about individual cache entries. You also explored how to use the verbose output (-v) to see more detailed records for each cache entry and learned how to check the disk usage for a specific builder instance by specifying its name.