docker image pull
| 描述 | 从注册表下载镜像 |
|---|---|
| 用法 | docker image pull [OPTIONS] NAME[:TAG|@DIGEST] |
| 别名 | docker pull |
描述
您的大多数镜像都将基于 Docker Hub 注册表中的基础镜像创建。
Docker Hub 包含许多预构建的镜像，您可以直接 `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 会终止拉取操作。