Does Docker build --no-cache actually download and refresh the base image?

Question

Does docker build --no-cache refresh updated remote base images or not? Documentation does not seem to specify.

Answer 1

The --no-cache option will rebuild the image without using the local cached layers. However, the FROM line will reuse the already pulled base image if it exists on the build host (the from line itself may not be cached, but the image it pulls is). If you want to pull the base image again, you can use the --pull option to the build command. E.g.

$ docker build --no-cache --pull -t new-image-name:latest .

To see all the options the build command takes, you can run

$ docker build --help

or see the documentation at https://docs.docker.com/engine/reference/commandline/build/

---

Here's an example for how you can test this behavior yourself:

$ # very simple Dockerfile
$ cat df.test
FROM busybox:latest
RUN echo hello >test.txt

$ # pull an older version of busybox
$ docker pull busybox:1.29.2
1.29.2: Pulling from library/busybox
8c5a7da1afbc: Pull complete
Digest: sha256:cb63aa0641a885f54de20f61d152187419e8f6b159ed11a251a09d115fdff9bd
Status: Downloaded newer image for busybox:1.29.2

$ # retag that locally as latest
$ docker tag busybox:1.29.2 busybox:latest

$ # run the build, note the image id at the end of each build step
$ DOCKER_BUILDKIT=0 docker build --no-cache -f df.test .
Sending build context to Docker daemon  23.04kB
Step 1/2 : FROM busybox:latest
 ---> e1ddd7948a1c
Step 2/2 : RUN echo hello >test.txt
 ---> Running in dba83fef49f9
Removing intermediate container dba83fef49f9
 ---> 1f824ff05612
Successfully built 1f824ff05612

$ # rerun the build, note step 1 keeps the same id and never pulled a new latest
$ DOCKER_BUILDKIT=0 docker build --no-cache -f df.test .
Sending build context to Docker daemon  23.04kB
Step 1/2 : FROM busybox:latest
 ---> e1ddd7948a1c
Step 2/2 : RUN echo hello >test.txt
 ---> Running in 73df884b0f48
Removing intermediate container 73df884b0f48
 ---> e5870de6c24f
Successfully built e5870de6c24f

$ # run with --pull and see docker update the latest image, new container id from step 1
$ DOCKER_BUILDKIT=0 docker build --no-cache --pull -f df.test .
Sending build context to Docker daemon  23.04kB
Step 1/2 : FROM busybox:latest
latest: Pulling from library/busybox
Digest: sha256:2a03a6059f21e150ae84b0973863609494aad70f0a80eaeb64bddd8d92465812
Status: Downloaded newer image for busybox:latest
 ---> 59788edf1f3e
Step 2/2 : RUN echo hello >test.txt
 ---> Running in 7204116ecbf4
Removing intermediate container 7204116ecbf4
 ---> 2c6d8c48661b
Successfully built 2c6d8c48661b

$ # one last run now that busybox:latest is updated shows the pull has nothing to do
$ DOCKER_BUILDKIT=0 docker build --no-cache --pull -f df.test .
Sending build context to Docker daemon  23.04kB
Step 1/2 : FROM busybox:latest
latest: Pulling from library/busybox
Digest: sha256:2a03a6059f21e150ae84b0973863609494aad70f0a80eaeb64bddd8d92465812
Status: Image is up to date for busybox:latest
 ---> 59788edf1f3e
Step 2/2 : RUN echo hello >test.txt
 ---> Running in f37e19024e99
Removing intermediate container f37e19024e99
 ---> 044a5d4011c4
Successfully built 044a5d4011c4

Answer 2

docker build --no-cache will rebuild your whole image without reusing cached layers but it will not pull the newest base image from the remote repository. It will just use your local stored image.