docker image pull
| 描述 | 从注册表下载镜像 |
|---|---|
| 用法 | docker image pull [OPTIONS] NAME[:TAG|@DIGEST] |
| 别名 | docker pull |
描述
您的大多数镜像将基于 Docker Hub 注册表中的基础镜像创建。
Docker Hub 包含许多预构建镜像，您可以 pull 并试用它们，而无需自己定义和配置。
要下载特定镜像或一组镜像（即仓库），请使用 docker image pull（或其简写 docker pull）。
代理配置
如果您位于 HTTP 代理服务器后面（例如在公司环境中），在连接到注册表之前，您可能需要配置 Docker 守护进程的代理设置，详细信息请参阅 dockerd 命令行参考。
并发下载
默认情况下，Docker 守护进程一次拉取一个镜像的三个层。如果您的网络带宽较低，这可能会导致超时问题，您可能需要通过 --max-concurrent-downloads 守护进程选项来降低此值。详细信息请参阅守护进程文档。
选项
| 选项 | 默认值 | 描述 |
|---|---|---|
-a, --all-tags | 下载仓库中所有带标签的镜像 | |
--disable-content-trust | true | 跳过镜像验证 |
--platform | API 1.32+ 如果服务器支持多平台，则设置平台 | |
-q, --quiet | 抑制详细输出 |
示例
从 Docker Hub 拉取镜像
要下载特定镜像或一组镜像（即仓库），请使用 docker image pull（或其简写 docker pull）。如果未提供标签，Docker Engine 将默认使用 :latest 标签。此示例拉取 debian:latest 镜像
$ docker image pull debian
Using default tag: latest
latest: Pulling from library/debian
e756f3fdd6a3: Pull complete
Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510
Status: Downloaded newer image for debian:latest
docker.io/library/debian:latest
Docker 镜像可以由多个层组成。在上面的示例中，该镜像由一个单层组成：e756f3fdd6a3。
层可以被镜像重用。例如，debian:bookworm 镜像与 debian:latest 共享其层。因此，拉取 debian:bookworm 镜像只拉取其元数据，而不拉取其层，因为该层已存在于本地
$ docker image pull debian:bookworm
bookworm: Pulling from library/debian
Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510
Status: Downloaded newer image for debian:bookworm
docker.io/library/debian:bookworm
要查看本地存在哪些镜像，请使用 docker images 命令
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
debian bookworm 4eacea30377a 8 days ago 124MB
debian latest 4eacea30377a 8 days ago 124MB
Docker 使用内容可寻址的镜像存储，镜像 ID 是涵盖镜像配置和层的 SHA256 摘要。在上面的示例中，debian:bookworm 和 debian:latest 具有相同的镜像 ID，因为它们是标记了不同名称的同一镜像。由于它们是同一镜像，它们的层只存储一次，不占用额外的磁盘空间。
有关镜像、层和内容可寻址存储的更多信息，请参阅 理解镜像、容器和存储驱动程序。
按摘要（不可变标识符）拉取镜像
目前为止，您已通过名称（和“标签”）拉取了镜像。使用名称和标签是处理镜像的便捷方式。使用标签时，您可以再次 docker pull 一个镜像，以确保您拥有该镜像的最新版本。例如，docker pull ubuntu:24.04 拉取 Ubuntu 24.04 镜像的最新版本。
在某些情况下，您不希望镜像更新到更新的版本，而是倾向于使用镜像的固定版本。Docker 允许您按镜像的摘要拉取镜像。按摘要拉取镜像时，您精确指定要拉取哪个版本的镜像。这样做可以让您将镜像“固定”到该版本，并保证您使用的镜像是始终相同的。
要了解镜像的摘要，请首先拉取该镜像。让我们从 Docker Hub 拉取最新的 ubuntu:24.04 镜像
$ docker pull ubuntu:24.04
24.04: Pulling from library/ubuntu
125a6e411906: Pull complete
Digest: sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
Status: Downloaded newer image for ubuntu:24.04
docker.io/library/ubuntu:24.04
Docker 在拉取完成后会打印镜像的摘要。在上面的示例中，镜像的摘要是
sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
Docker 在推送到注册表时也会打印镜像的摘要。如果您想固定到您刚推送的镜像版本，这可能会很有用。
拉取镜像时，摘要取代标签的位置，例如，要按摘要拉取上面的镜像，请运行以下命令
$ docker pull ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
docker.io/library/ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30: Pulling from library/ubuntu
Digest: sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
Status: Image is up to date for ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
docker.io/library/ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
摘要也可以用于 Dockerfile 的 FROM 中，例如
FROM ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
LABEL org.opencontainers.image.authors="some maintainer <maintainer@example.com>"注意
使用此功能将镜像“固定”到特定时间点的一个版本。因此，Docker 不会拉取镜像的更新版本，这些版本可能包含安全更新。如果您想拉取更新的镜像，您需要相应地更改摘要。
从不同的注册表拉取
默认情况下，docker pull 从 Docker Hub 拉取镜像。也可以手动指定要从中拉取的注册表的路径。例如，如果您已设置本地注册表，可以指定其路径从中拉取。注册表路径类似于 URL，但不包含协议指定符（https://）。
以下命令从监听端口 5000 的本地注册表（myregistry.local:5000）拉取 testing/test-image 镜像
$ docker image pull myregistry.local:5000/testing/test-image
注册表凭据由 docker login 管理。
Docker 使用 https:// 协议与注册表通信，除非该注册表允许通过不安全连接访问。更多信息请参阅不安全注册表部分。
拉取包含多个镜像的仓库（-a, --all-tags）
默认情况下，docker pull 从注册表拉取单个镜像。一个仓库可以包含多个镜像。要从仓库中拉取所有镜像，在使用 docker pull 时提供 -a（或 --all-tags）选项。
此命令拉取 ubuntu 仓库中的所有镜像
$ docker image pull --all-tags ubuntu
Pulling repository ubuntu
ad57ef8d78d7: Download complete
105182bb5e8b: Download complete
511136ea3c5a: Download complete
73bd853d2ea5: Download complete
....
Status: Downloaded newer image for ubuntu
拉取完成后，使用 docker image ls 命令（或其简写 docker images）查看已拉取的镜像。下面的示例显示了本地存在的所有 ubuntu 镜像
$ docker image ls --filter reference=ubuntu
REPOSITORY TAG IMAGE ID CREATED SIZE
ubuntu 22.04 8a3cdc4d1ad3 3 weeks ago 77.9MB
ubuntu jammy 8a3cdc4d1ad3 3 weeks ago 77.9MB
ubuntu 24.04 35a88802559d 6 weeks ago 78.1MB
ubuntu latest 35a88802559d 6 weeks ago 78.1MB
ubuntu noble 35a88802559d 6 weeks ago 78.1MB
取消拉取
终止 docker pull 进程（例如，在终端中运行时按下 CTRL-c）将终止拉取操作。
$ docker pull ubuntu
Using default tag: latest
latest: Pulling from library/ubuntu
a3ed95caeb02: Pulling fs layer
236608c7b546: Pulling fs layer
^C
当守护进程与客户端（发起拉取方）之间的连接因任何原因中断或丢失，或命令被手动终止时，Engine 将终止拉取操作。