moby / moby/moby

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

Open
#50,834 7 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area/images backlog kind/enhancement status/0-triage version/28.3
Dominant language
Go
Stars
72.1k
Forks
19.2k
Avg merge
1d 17h
Merged PRs (30d)
164

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the issue with the documented docker save and docker load commands, comparing image-ID and repository:tag references. Trace the docker save and docker load entry points and identify where tag metadata is selected or restored. Done means both reference forms reload with equivalent repository and tag metadata.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, go
Domain
cli, devops
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.