Remote base image used instead of local when `# syntax` is used

[SpecLad]

Contributing guidelines and issue reporting guide

• I've read the contributing guidelines and wholeheartedly agree. I've also read the issue reporting guide.

Well-formed report checklist

• I have found a bug that the documentation does not mention anything about my problem
• I have found a bug that there are no open or closed issues that are related to my problem
• I have provided version/information about my environment and done my best to provide a reproducer

Description of bug

Bug description

If the Dockerfile contains a # syntax directive, then Docker will prefer fetching the base image from Docker Hub, even if a local image with the same name already exists.

Reproduction

First, create two files:

Dockerfile.base:

FROM busybox

RUN echo "This is Base" > /root/base.txt

Dockerfile.derived:

# syntax=docker/dockerfile:1

ARG BASE
FROM ${BASE}

RUN echo "This is Derived" > /root/derived.txt

Now, run the following:

base_name=base
docker build -t ${base_name} -f Dockerfile.base . && docker build --build-arg BASE=${base_name} -t derived -f Dockerfile.derived . && docker run -ti --rm derived ls /root

The output of the last command is:

base.txt     derived.txt

And this is okay!

Now change the tag for the base image to something that exists on Docker Hub and try again:

base_name=alpine
docker build -t ${base_name} -f Dockerfile.base . && docker build --build-arg BASE=${base_name} -t derived -f Dockerfile.derived . && docker run -ti --rm derived ls /root

This time, the output is:

derived.txt

This indicates that the built base image was not actually used as the base for the derived image. It's easy to check that Docker actually fetched the image from Docker Hub with the same name:

$ docker run -ti --rm derived cat /etc/os-release
NAME="Alpine Linux"
ID=alpine
VERSION_ID=3.24.1
PRETTY_NAME="Alpine Linux v3.24"
HOME_URL="https://alpinelinux.org/"
BUG_REPORT_URL="https://gitlab.alpinelinux.org/alpine/aports/-/issues"

This behavior doesn't make much sense to me. Clearly Docker is able to use a local image as the base (the first test proves it), so why would it fetch a remote image if a local one is available?

Version information

Client: Docker Engine - Community
 Version:           29.6.1
 API version:       1.55
 Go version:        go1.26.4
 Git commit:        8900f1d
 Built:             Fri Jun 26 11:40:19 2026
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          29.6.1
  API version:      1.55 (minimum version 1.40)
  Go version:       go1.26.4
  Git commit:       8ec5ab3
  Built:            Fri Jun 26 11:40:19 2026
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          v2.2.6
  GitCommit:        11ce9d5f3c68c941867e82890e93e815c1304f1b
 runc:
  Version:          1.3.6
  GitCommit:        v1.3.6-0-g491b69ba
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

github.com/docker/buildx v0.35.0 a319e5b15052cf6557ceb666eb8ff6e32380b782

[thaJeztah]

Clearly Docker is able to use a local image as the base (the first test proves it), so why would it fetch a remote image if a local one is available?

I wonder if it's the reverse; IIRC, BuildKit checks if the base image that's cached locally is up-to-date; for the base case (image doesn't exist on docker hub), that resulted in a 404, in which case it fell back to using the local image cache. And in the "image does exist on Docker Hub", it found the image outdated (digest changed), so pulled the latest variant.

I"m sure @tonistiigi could say for sure.

[SpecLad]

IIRC, BuildKit checks if the base image that's cached locally is up-to-date; for the base case (image doesn't exist on docker hub), that resulted in a 404, in which case it fell back to using the local image cache. And in the "image does exist on Docker Hub", it found the image outdated (digest changed), so pulled the latest variant.

I can believe it, but it doesn't seem like useful behavior to me. docker build already has a --pull option to enable pulling base images, it should not be the default (and it isn't in the absense of # syntax).