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
当守护程序和客户端（启动拉取）之间的连接因任何原因中断或丢失，或者命令被手动终止时，引擎将终止拉取操作。