Docker caches image build results to accelerate subsequent rebuilds. While this mechanism is generally reliable, sometimes you’ll want to rebuild an image without using the cache. This could be to diagnose issues or check the complete build procedure will be reproducible in a clean environment.
In this article, you’ll learn how to achieve a fresh build without manually deleting the cache. You’ll also see how to pull updated base images so your build matches the output that a new Docker installation would produce.
How the Cache Works
Here’s a simple Dockerfile:
Populate the sample files in your working directory and build the image:
The output will look similar to this:
Now modify 2.txt and then rebuild the image:
The second build stage shows Using cache because the contents of 1.txt haven’t changed. The intermediate layer with ID db61ff73c0b5 gets reused for the new build.
Disabling the Cache
You can disable use of the intermediate layer cache by including the –no-cache flag when you run docker build:
This time a new image layer, ID 1590b2407dd4, has been created by the second build stage, even though 1.txt remains unmodified.
You can use the –no-cache flag to force a rebuild when you suspect the cache is stale or you want to start from scratch. Build performance will be reduced because Docker will need to recreate every layer.
Pulling Updated Base Images
Another form of caching concerns the base images which your Dockerfile references in its FROM instructions. The example image above uses alpine:latest as its base. Docker won’t automatically pull an updated version of alpine:latest, unless the image doesn’t already exist on your host.
This means the first build of a Dockerfile will pull down the base images you need, as long as you don’t already have them. Subsequent rebuilds won’t refresh the images so you could be building on an outdated base. Building the image on a different Docker host might not produce the same output if that host pulls a newer version of the base.
You can force Docker to check for updated base images at build time by adding the –pull flag to your docker build command. This is separate to –no-cache. Using –pull will retrieve the image tag’s manifest from its registry and compare it to the version on your machine. The new image will be pulled from the registry when there’s a discrepancy in the manifests.
The above example shows how the build output changes when the –pull flag is used. Docker tries to pull the Alpine base image, even though it’s already on the machine from the earlier example builds. The image digest (SHA) is printed to the terminal. In this case the digest is unchanged from the local version so Docker reports that the image is already up to date.
The –no-cache and –pull flags can be used independently or in combination. Adding them both gives you the cleanest slate for starting your build, forcing Docker to check for updated base images and disregard any previously created layers. It’s equivalent to running the build on a newly installed Docker host.
Using Docker Compose
Docker Compose supports both the –no-cache and –pull flags too. They have the same effect as their docker build counterparts.
Cleaning the Build Cache
You can clean the build cache to guarantee it’s disused. This also helps to free up excess disk space consumed by cached build layers.
Run the docker builder prune command to empty your cache. It only works when you’re building images with the modern BuildKit build engine.
Running the command without arguments only removes the dangling build cache. This relates to caches that relate to images no longer present on your host. Add the -a flag to completely empty the cache, including layers that are used by images:
Pruning also accepts a –filter flag that can be used to target caches modified before or since a particular time period.
Summary
The Docker build cache improves performance by reusing intermediate image layers between builds. This avoids wasted work to recreate layers that already exist and haven’t changed. While the build cache is generally desirable, there are scenarios where you might want to run a build without it. Adding the –no-cache flag to your builds provides an accurate perspective of what the build would produce when run on a new host.
Stale base images need to be considered alongside the build cache too. Docker reuses local versions of base images by default, which can cause you to build new images on an outdated base. Using the –pull flag forces Docker to check for updated base images before it starts the build, giving you greater consistency across different environments.
