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
Digest 也可以用在 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
当守护进程与客户端（发起拉取操作）之间的连接因任何原因中断或丢失，或者命令被手动终止时，引擎将终止拉取操作。