What is build cache in `docker system df`

Question

run docker system df will display a row of Build Cache. What does this mean? In my machine this line is always showing 0 for all fields.

$ sudo docker system df
TYPE                TOTAL               ACTIVE              SIZE                RECLAIMABLE
Images              5                   3                   352.9MB             352.9MB (100%)
Containers          7                   0                   26.29MB             26.29MB (100%)
Local Volumes       1                   1                   0B                  0B
Build Cache         0                   0                   0B                  0B

Answer 1

The Build Cache lines refer to the cache used by BuildKit which is included with 18.09 and newer versions of docker. It is not enabled by default, so unless you have switched it on, you can expect this to read 0. This is the cache used when building and rebuilding images to speed up builds and reuse shared layers between images. It also reduces the size of the images pushed to a registry when layers are reused from prior builds.

The cache from BuildKit is buried since it runs from containerd rather than directly in docker, so you can view the disk used for this cache and then prune it with commands like:

docker builder prune

If you run builds without BuildKit, the cache for these will be cleaned up when you prune images on the host.

Answer 2

The command docker system df shows the docker disk usage.

Images shows the disk usage for the docker images that are not running.

Containers shows the disk usage for the docker containers running.

Local Volumes shows the disk usage for the volumes you are using on your running containers.

And, recently, it was added a new section called Build Cache, which shows the disk usage for the cache files docker is using while building and running containers.

It was not there before, it was added on May 18, 2018, but they forgot to add it to the documentation, so you can't see it listed on the system df docs.

I'd just sent a PR so you can see it on the example output so I hope they can merge it soon.

Edit: The PR was merged, you can now find the examples on the official documentation.