Docker save is not exporting image tag when image is referenced by ID

[kovalensue]

Description

If the image is referenced by its ID in docker save <image_id> | gzip > <path_to_archive>.tgz, the tag metadata is not included in the result. When the archive is then used to load images using docker load <path_to_archive>.tgz, images are loaded without the repository and tag information.

If the image is referenced by the full <repository:tag> string during the save, tags are included in the exported metadata as expected.

This behaviour is inconsistent and feels counterintuitive. The way of referencing images in the docker save command should not change the expected output of that command, in my opinion.

Reproduce

1. Build an image using docker buildx build -f <path_to_dockerfile> -t <some_tag> .
2. Save image into archive and reference image using its ID: docker save $(docker images -q) | gzip > <path_to_archive>.tgz
3. Delete local images docker image rm $(docker images -q)
4. Load image from the archive docker load < path_to_archive>.tgz
5. Print image info docker images

Expected behavior

docker save should not export different image metadata when using a different way of referencing the image, i.e.:

Images saved via docker save <image_id> or docker save <repository>:<tag> should have the same metadata (especially identifiers) when loaded.

docker version

Client: Docker Engine - Community
 Version:           28.3.3
 API version:       1.51
 Go version:        go1.24.5
 Git commit:        980b856
 Built:             Fri Jul 25 11:34:04 2025
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          28.3.3
  API version:      1.51 (minimum version 1.24)
  Go version:       go1.24.5
  Git commit:       bea959c
  Built:            Fri Jul 25 11:34:04 2025
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.7.27
  GitCommit:        05044ec0a9a75232cad458027ca83437aae3f4da
 runc:
  Version:          1.2.5
  GitCommit:        v1.2.5-0-g59923ef
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

docker info

Client: Docker Engine - Community
 Version:    28.3.3
 Context:    default
 Debug Mode: false
 Plugins:
  buildx: Docker Buildx (Docker Inc.)
    Version:  v0.26.1
    Path:     /usr/libexec/docker/cli-plugins/docker-buildx
  compose: Docker Compose (Docker Inc.)
    Version:  v2.39.1
    Path:     /usr/libexec/docker/cli-plugins/docker-compose

Server:
 Containers: 0
  Running: 0
  Paused: 0
  Stopped: 0
 Images: 9
 Server Version: 28.3.3
 Storage Driver: overlay2
  Backing Filesystem: extfs
  Supports d_type: true
  Using metacopy: false
  Native Overlay Diff: true
  userxattr: false
 Logging Driver: json-file
 Cgroup Driver: systemd
 Cgroup Version: 2
 Plugins:
  Volume: local
  Network: bridge host ipvlan macvlan null overlay
  Log: awslogs fluentd gcplogs gelf journald json-file local splunk syslog
 CDI spec directories:
  /etc/cdi
  /var/run/cdi
 Swarm: inactive
 Runtimes: io.containerd.runc.v2 runc
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: 05044ec0a9a75232cad458027ca83437aae3f4da
 runc version: v1.2.5-0-g59923ef
 init version: de40ad0
 Security Options:
  apparmor
  seccomp
   Profile: builtin
  cgroupns
 Kernel Version: 6.8.0-65-generic
 Operating System: Ubuntu 22.04.5 LTS
 OSType: linux
 Architecture: x86_64
 CPUs: 12
 Total Memory: 30.79GiB
 Name: <not_gonna_tell>
 ID: a4fd1b44-abe0-4881-a9da-aeb2fc6c8707
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
 Experimental: false
 Insecure Registries:
  ::1/128
  127.0.0.0/8
 Live Restore Enabled: false

Additional Info

Full example in terminal:

$ docker buildx build -f ~/tmp/Dockerfile.alpine-3.21-pg16.6 -t posgres-16:latest .
[+] Building 26.2s (10/10) FINISHED                                                                                                               docker:default
 => [internal] load build definition from Dockerfile.alpine-3.21-pg16.6                                                                                     0.0s
...

$ docker images
REPOSITORY   TAG       IMAGE ID       CREATED          SIZE
posgres-16   latest    141362f404e1   21 seconds ago   373MB

$ docker save $(docker images -q) | gzip > ~/tmp/images_test.tgz

$ docker image rm $(docker images -q)
Untagged: posgres-16:latest
Deleted: sha256:141362f404e1226ba6f198b3711a076192a1638a00922754b4bdbf090eca73b5

$ docker load < ~/tmp/images_test.tgz
Loaded image ID: sha256:141362f404e1226ba6f198b3711a076192a1638a00922754b4bdbf090eca73b5

$ docker images
REPOSITORY   TAG       IMAGE ID       CREATED         SIZE
<none>       <none>    141362f404e1   4 minutes ago   373MB

[thaJeztah]

(copying over my comments from docker/cli#6383)

It's possible that this was by design; the same image ID / digest can have many tags / names when saving an image using its ID or digest, this could produce an inconsistent result depending on what tags happen to be present in the local image cache that refer to the digest.

Possibly that could be addressed if the tag + digest format would be accepted and to indicate the tag to export (e.g. myimage:latest@sha256:xxxxx), but that may require some special handling (currently that format discards the tag, and takes the digest as source of truth).

We should look if we can make this work more "organically", but with these, the devil is sometimes in the details, so we need to look carefully, also to not break existing behavior.

With the migration to the containerd image store, sometimes things are even more "subtle", and for some of those there's challenges to keep the same UX, but also expose additional functionality that became possible (around multi-platform images); see moby/moby#49995

[thaJeztah]

Oh, I should mention that perhaps for your use-case, the --output option on docker build / docker buildx build could be of interest; it allows you to save the image directly from your build, without storing it in the docker daemon's local image store first; see https://docs.docker.com/reference/cli/docker/buildx/build/#output

Documentation probably could use some further refinement on the differences between the docker and oci format, but you can pick either one to export a tar that can be imported;

docker buildx build --tag myimage --output type=docker,dest=./myimage.tar .
docker image load -i ./myimage.tar
Loaded image: myimage:latest


docker buildx build --tag myimage2 --output type=oci,dest=./myimage-oci.tar .
docker image load -i ./myimage-oci.tar
Loaded image: myimage2:latest


docker image ls --tree
IMAGE                ID             DISK USAGE   CONTENT SIZE   EXTRA
myimage2:latest      65f5610f1675        662MB          160MB
└─ linux/arm64       65f5610f1675        662MB          160MB
myimage:latest       239751afb245        662MB          160MB
└─ linux/arm64       239751afb245        662MB          160MB

If you specify - as path, it outputs the tar stream to stdout; I see you are compressing the resulting tar, but I think layers inside the tar would already be compressed (gzip by default), so probably the extra compression won't save much space. You can control the compression used for the layers with the compression option on the output flag as well (e.g. if you want to use zstd, which is slightly less portable, but should be supported by current engines); https://docs.docker.com/build/exporters/#configuration-options

[kovalensue]

This looks interesting. However, saving from the daemon local store is beneficial in my case because I can save multiple images created during the CI job (in Gitlab pipeline) into a single archive, which simplifies the workflow of passing the resulting archive to other jobs in the pipeline. Nevertheless, thanks for the tip, will take a look 😉

[thaJeztah]

For sure! Yes I definitely wouldn't have insight in your full use-case, but thought it could be good to mention as an option to explore and play with on a rainy afternoon. For multiple images, it's worth looking at docker bake / docker buildx bake, (or docker compose) which allows defining a pipeline to run multiple builds and/or artifacts;

• https://docs.docker.com/build/bake/
• https://docs.docker.com/reference/compose-file/build/