docker pull 命令教程：下载镜像（--platform、-q、指定 digest）

Q: 重复运行 docker pull 会重新下载镜像吗？

如果镜像已是最新，输出会显示 Image is up to date；示例中的 digest 和镜像引用也与首次下载相同。

Q: 如何固定下载的镜像版本？

在镜像名称后使用 @sha256: 加上 digest，例如 alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0。

Q: tag 不存在时会看到什么错误？

示例中的 nginx:9.99 返回 not found，表示 registry 找不到该镜像引用。

Q: 指定 --platform 后，镜像一定会以该平台出现在 inspect 结果中吗？

示例指定 linux/arm64 拉取后，docker image inspect 显示 linux/amd64；可以用 docker images --tree 查看该镜像列出的多个平台变体。

docker pull 从镜像仓库下载镜像；镜像与标签的概念请参见镜像。

语法

docker pull [选项] 名称[:标签|@摘要]

选项

选项	说明
`-a, --all-tags`	下载该 repository 中所有带标签的镜像
`--platform 字符串`	如果服务器支持多平台，则指定要下载的平台
`-q, --quiet`	隐藏详细输出

示例

下载镜像并再次拉取

$ docker pull alpine:3.23
3.23: Pulling from library/alpine
5e9b4a97f639: Pulling fs layer
5e9b4a97f639: Download complete
97ab9557f126: Download complete
79dff55e92ba: Download complete
5e9b4a97f639: Pull complete
Digest: sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63
Status: Downloaded newer image for alpine:3.23
docker.io/library/alpine:3.23

$ docker pull alpine:3.23
3.23: Pulling from library/alpine
Digest: sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63
Status: Image is up to date for alpine:3.23
docker.io/library/alpine:3.23

首次拉取会显示层的下载进度、digest，以及 Downloaded newer image 状态。
再次拉取时，digest 相同且显示 Image is up to date，不会重复列出层的下载进度。
未指定 registry 时，输出的完整名称是 docker.io/library/alpine:3.23。

静默模式与不存在的 tag

$ docker pull -q redis:8-alpine
docker.io/library/redis:8-alpine

$ docker pull nginx:9.99
Error response from daemon: failed to resolve reference "docker.io/library/nginx:9.99": docker.io/library/nginx:9.99: not found

-q 会隐藏下载进度等详细输出，此示例只打印镜像的完整名称。
找不到 tag 9.99 时，daemon 会返回 not found，并列出无法解析的完整镜像引用。

指定平台并查看平台变体

$ docker pull --platform linux/arm64 alpine:3.23
3.23: Pulling from library/alpine
197a036d7c64: Pulling fs layer
197a036d7c64: Download complete
4f0cdf9143b4: Download complete
8b7a0920489a: Download complete
197a036d7c64: Pull complete
Digest: sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63
Status: Image is up to date for alpine:3.23
docker.io/library/alpine:3.23

$ docker image inspect -f '{{.Os}}/{{.Architecture}}' alpine:3.23
linux/amd64

$ docker images --tree alpine:3.23
IMAGE                   ID             DISK USAGE   CONTENT SIZE   EXTRA
alpine:3.23             ff7f0c727dd7       26.6MB         8.21MB        
├─ linux/amd64          3d67941fed5a       12.9MB         3.85MB        
├─ linux/arm/v6         806bbcf86639           0B             0B        
├─ linux/arm/v7         b43a13ac240c           0B             0B        
├─ linux/arm64/v8       8793abc47938       13.5MB         4.19MB        
├─ linux/386            7811c228ca81           0B             0B        
├─ linux/ppc64le        cc3ef1f3240a           0B             0B        
├─ linux/riscv64        1e12543f1917           0B             0B        
└─ linux/s390x          ac74ebe0c48b           0B             0B

使用 --platform linux/arm64 下载了 arm64 版本的层，但状态仍为 Image is up to date：alpine:3.23 是多平台镜像，名称和 digest 都没有变化，只是本机多了另一个平台的内容。
因此，docker image inspect 默认仍显示本机平台 linux/amd64；要查看其他平台，请使用下面的 docker images --tree。
docker images --tree 会列出 amd64、arm64/v8 等平台变体；此处 arm64/v8 的磁盘使用量为 13.5MB。

用 digest 固定镜像版本

$ docker pull alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0
docker.io/library/alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0: Pulling from library/alpine
d0c1d894c237: Pulling fs layer
d0c1d894c237: Download complete
d836c7fd48f4: Download complete
047d62850641: Download complete
d0c1d894c237: Pull complete
Digest: sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0
Status: Downloaded newer image for alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0
docker.io/library/alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0

$ docker images alpine
IMAGE                                                                            ID             DISK USAGE   CONTENT SIZE   EXTRA
alpine:3.23                                                                      ff7f0c727dd7       26.6MB         8.21MB        
alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0   85fe1e81d675         13MB         3.94MB

在镜像名称后加上 @sha256: 和 digest，即可用 digest 指定镜像，而不是使用可能变化的 tag。
输出中的 Digest 与指定的 digest 相同，状态为 Downloaded newer image。
docker images alpine 同时列出了 alpine:3.23 和 digest 形式的引用，两者的 ID 不同：这个 digest 对应较早的 3.23 版本，而 3.23 这个 tag 后来已指向更新的构建。这正是使用 digest 固定版本的原因：tag 会变化，digest 不会。

动手练习

练习：使用 digest 拉取题目中的 Alpine 镜像，并查看本机的 Alpine 镜像列表。

答案

docker pull alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0
docker images alpine

常见问题

重复运行 docker pull 会重新下载镜像吗？

如果镜像已是最新，输出会显示 Image is up to date；示例中的 digest 和镜像引用也与首次下载相同。

如何固定下载的镜像版本？

在镜像名称后使用 @sha256: 加上 digest，例如 alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0。

tag 不存在时会看到什么错误？

示例中的 nginx:9.99 返回 not found，表示 registry 找不到该镜像引用。

指定 --platform 后，镜像一定会以该平台出现在 inspect 结果中吗？

示例指定 linux/arm64 拉取后，docker image inspect 显示 linux/amd64；可以用 docker images --tree 查看该镜像列出的多个平台变体。

更新于 2026年10月26日