跳到主要内容

podman pull - 从注册表中拉取镜像

概述​

podman pull [options] source [source...]

podman image pull [options] source [source...]

podman pull [options][*transport*]name[:tag|@digest]

podman image pull [options][*transport*]name[:tag|@digest]

描述​

podman pull 命令用于从注册表中复制镜像到本地机器。该命令可以拉取一个或多个镜像。如果命令行参数中的镜像引用不包含注册表，则它被称为“短名称”引用。如果镜像是“短名称”引用，且 short-name-aliases.conf 中没有为短名称指定别名，Podman 会提示用户指定要从哪个容器注册表拉取镜像。如果未指定镜像标签，podman pull 默认拉取名为 latest 的镜像（如果存在）。拉取镜像后，podman 会打印完整的镜像ID。podman pull 还可以使用摘要 podman pull image@digest 来拉取镜像，并且可以使用不同的传输方式从归档和本地存储中拉取镜像。

重要提示：镜像存储在本地镜像存储中。

源​

SOURCE 是容器镜像被拉取的位置。它支持 containers-transports(5) 中列出的所有传输方式。如果没有指定传输方式，输入将进行短名称解析，并使用 docker（即容器注册表）传输方式。对于远程客户端，包括Mac和Windows（不包括WSL2）机器，docker 是唯一支持的传输方式。

从容器注册表中拉取镜像​

这些示例演示了如何使用 podman pull 命令从各种源拉取容器镜像。

podman pull quay.io/username/myimage

这条命令将从 quay.io 注册表中拉取名为 username/myimage 的镜像。如果 myimage 没有指定标签，则默认拉取名为 latest 的标签（如果存在）。

使用短名称解析从容器注册表拉取镜像​

podman pull fedora

这条命令将尝试解析短名称 fedora，并根据系统配置和本地别名文件 short-name-aliases.conf 来确定从哪个注册表拉取镜像。如果别名未配置，用户可能会被提示选择注册表。

通过 docker 传输方式从容器注册表拉取镜像​

podman pull docker://quay.io/username/myimage

即使不指定传输方式，podman 通常也会默认使用 docker 传输方式。但这条命令显式地指定了使用 docker 传输方式从 quay.io 拉取镜像。

从本地目录拉取镜像​

podman pull dir:/tmp/myimage

这条命令将从本地 /tmp/myimage 目录拉取镜像。这个目录应该包含一个有效的容器镜像。

从 docker-archive 格式的归档文件中拉取镜像​

podman pull docker-archive:/tmp/myimage

这条命令将从 /tmp/myimage 路径下的 docker-archive 格式的归档文件中拉取镜像。这种格式的归档文件通常包含一个或多个 Docker 镜像。

从本地 Docker 守护进程拉取镜像​

sudo podman pull docker-daemon:docker.io/library/myimage:33

这条命令需要从本地运行的 Docker 守护进程中拉取名为 myimage，标签为 33 的镜像。注意，由于 podman 和 docker 守护进程通常不会在同一台机器上同时运行，这个命令通常用于那些同时运行了 Docker 和 Podman 的环境中，比如使用 podman-docker 桥接工具的场景。

从 OCI-archive 格式的归档文件中拉取镜像​

podman pull oci-archive:/tmp/myimage

这条命令将从 /tmp/myimage 路径下的 OCI-archive 格式的归档文件中拉取镜像。OCI 归档格式是一种标准化的容器镜像格式。

在使用 podman pull 时，确保你有适当的权限（可能需要 sudo），并且你的系统已经安装了 Podman 及其依赖项。同时，根据你的网络环境和镜像源的不同，拉取镜像的速度可能会有所不同。

以下是将上述内容生成的Markdown表格：

选项描述
--all-tags, -a拉取仓库中所有标签的镜像。当使用此标志时，Podman始终使用docker.io作为未限定镜像名称的默认注册表。*重要提示：当使用 all-tags 标志时，Podman 不会遍历 containers-registries.conf(5) 中的搜索注册表，而是始终对未限定的镜像名称使用 docker.io。
--arch指定要拉取的镜像的架构。
--authfile指定包含认证信息的文件路径，用于访问私有注册表。
--cert-dir指定包含TLS证书和密钥的目录。
--creds在命令行上直接提供用户名和密码，格式为username:password。
--decryption-key指定用于解密加密镜像层的密钥。
--disable-content-trust禁用镜像内容的信任检查。
--help, -h显示podman pull命令的帮助信息。
--os.pull指定拉取镜像时考虑的操作系统类型。
--platform指定拉取镜像的平台，包括架构和操作系统。
--quiet, -q在拉取镜像时抑制输出信息。
--retry如果拉取失败，指定重试的次数。
--retry-delay指定每次重试之间的延迟时间。
--tls-verify启用或禁用TLS验证，以确保与注册表的安全通信。
--variant.container指定容器镜像的变体或类型。

这个表格简要概述了podman pull命令的一些常用选项及其描述。在使用这些选项时，请确保了解它们的含义和潜在影响，并根据实际情况进行选择。

文件​

short-name-aliases.conf (/var/cache/containers/short-name-aliases.conf, $HOME/.cache/containers/short-name-aliases.conf)

当用户指定的镜像不包含存储镜像的容器注册表时，这被称为短名称。使用未限定搜索注册表涉及一个模糊性，因为不清楚应从哪个注册表拉取给定短名称引用的镜像。

使用短名称存在被劫持的注册表命名空间的风险。如果未限定搜索注册表设置为 ["public-registry.com", "my-private-registry.com"]，攻击者可能会接管public-registry.com的命名空间，这样，镜像可能会从public-registry.com而不是预期的源my-private-registry.com被拉取。

虽然强烈建议始终使用完全限定的镜像引用，但使用短名称的现有部署可能不易更改。为了绕过上述模糊性，可以配置所谓的短名称别名，它们指向完全限定的镜像引用。发行版通常在/etc/containers/registries.conf.d/目录中提供一个默认的shortnames.conf扩展文件。管理员可以使用此目录添加自己的本地短名称扩展文件。

在拉取镜像时，如果用户没有指定完整的注册表，容器引擎会尝试将短名称扩展为全名。如果命令在终端中执行，系统会提示用户从registries.conf中定义的默认未限定注册表列表中选择一个注册表。用户的选择然后存储在缓存文件中，以供将来所有短名称扩展使用。rootful短名称存储在/var/cache/containers/short-name-aliases.conf中。rootless短名称存储在$HOME/.cache/containers/short-name-aliases.conf文件中。

有关短名称的更多信息，请参见containers-registries.conf(5)。

registries.conf (/etc/containers/registries.conf)

registries.conf 是配置文件，它指定了当补全不包含注册表或域部分的镜像名称时，应咨询哪些容器注册表。

注意：使用环境变量 TMPDIR 可以更改下载的容器镜像的临时存储位置。Podman 默认使用 /var/tmp。

示例​

使用短名称解析拉取单个镜像。

podman pull alpine:latest
解析 "alpine" 为别名 (/etc/containers/registries.conf.d/000-shortnames.conf)
尝试拉取 docker.io/library/alpine:latest...
获取镜像源签名
复制 blob 5843afab3874 完成
复制配置 d4ff818577 完成
将清单写入镜像目标
存储签名
d4ff818577bc193b309b355b02ebc9220427090057b54a59e73b79bdfe139b83

使用/不使用短名称解析拉取多个镜像。

podman pull busybox:musl alpine quay.io/libpod/cirros
尝试拉取 docker.io/library/busybox:musl...
获取镜像源签名
复制 blob 0c52b060233b [----------------------------------] 0.0b / 0.0b
复制配置 9ad2c435a8 完成
将清单写入镜像目标
存储签名
9ad2c435a887e3f723654e09b48563de44aa3c7950246b2e9305ec85dd3422db
尝试拉取 docker.io/library/alpine:latest...
获取镜像源签名
复制 blob 5843afab3874 [--------------------------------------] 0.0b / 0.0b
复制配置 d4ff818577 完成
将清单写入镜像目标
存储签名
d4ff818577bc193b309b355b02ebc9220427090057b54a59e73b79bdfe139b83
尝试拉取 quay.io/libpod/cirros:latest...
获取镜像源签名
复制 blob 8da581cc9286 完成
复制 blob 856628d95d17 完成
复制 blob f513001ba4ab 完成
复制配置 3c82e4d066 完成
将清单写入镜像目标
存储签名
3c82e4d066cf6f9e50efaead6e3ff7fddddf5527826afd68e5a969579fc4db4a

在这些示例中，podman pull 命令被用来拉取具有和不具有短名称解析的镜像。短名称解析允许用户通过指定部分名称（例如只提供镜像名称而不是完整的注册表和路径）来拉取镜像。registries.conf 文件中的配置决定了这些短名称如何被解析为完整的镜像引用。在拉取过程中，Podman 会显示它正在尝试从哪个注册表拉取镜像，以及镜像的拉取进度和结果。

使用镜像摘要拉取镜像​

podman pull alpine@sha256:d7342993700f8cd7aba8496c2d0e57be0666e80b4c441925fc6f9361fa81d10e
尝试拉取 docker.io/library/alpine@sha256:d7342993700f8cd7aba8496c2d0e57be0666e80b4c441925fc6f9361fa81d10e...
获取镜像源签名
复制 blob 188c0c94c7c5 完成
复制配置 d6e46aa247 完成
将清单写入镜像目标
存储签名
d6e46aa2470df1d32034c6707c8041158b652f38d2a9ae3d7ad7e7532d22ebe0

使用认证文件拉取镜像​

podman pull --authfile temp-auths/myauths.json docker://docker.io/umohnani/finaltest
尝试拉取 docker.io/umohnani/finaltest:latest...获取镜像源签名
复制 blob sha256:6d987f6f42797d81a318c40d442369ba3dc124883a0964d40b0c8f4f7561d913
 1.90 MB / 1.90 MB [========================================================] 0s
复制配置 sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156
 1.41 KB / 1.41 KB [========================================================] 0s
将清单写入镜像目标
存储签名
03290064078cb797f3e0a530e78c20c13dd22a3dd3adf84a5da2127b48df0438

通过认证拉取镜像​

podman pull --creds testuser:testpassword docker.io/umohnani/finaltest
尝试拉取 docker.io/umohnani/finaltest:latest...获取镜像源签名
复制 blob sha256:6d987f6f42797d81a318c40d442369ba3dc124883a0964d40b0c8f4f7561d913
 1.90 MB / 1.90 MB [========================================================] 0s
复制配置 sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156
 1.41 KB / 1.41 KB [========================================================] 0s
将清单写入镜像目标
存储签名
03290064078cb797f3e0a530e78c20c13dd22a3dd3adf84a5da2127b48df0438

通过覆盖主机架构拉取镜像​

podman pull --arch=arm arm32v7/debian:stretch
尝试拉取 docker.io/arm32v7/debian:stretch...
获取镜像源签名
复制 blob b531ae4a3925 完成
复制配置 3cba58dad5 完成
将清单写入镜像目标
存储签名
3cba58dad5d9b35e755b48b634acb3fdd185ab1c996ac11510cc72c17780e13c

在这个示例中，podman pull 命令使用了 --arch=arm 参数来指定目标架构为 ARM。这样，即使运行 podman 的主机使用的是不同的架构（例如 x86_64），也可以拉取并运行 ARM 架构的镜像。命令成功拉取了 arm32v7/debian:stretch 镜像，并显示了镜像的 ID。

使用最多6次重试和10秒间隔静默拉取镜像​

podman --remote pull -q --retry 6 --retry-delay 10s ubi9
4d6addf62a90e392ff6d3f470259eb5667eab5b9a8e03d20b41d0ab910f92170

在这个示例中，podman 命令使用了几个额外的参数来增强拉取过程的健壮性。--remote 参数允许通过远程 API 拉取镜像。-q 参数用于静默模式，即不显示详细的输出信息。--retry 6 指定了最多尝试拉取6次，如果一次尝试失败，则会等待指定的延迟时间后重试。--retry-delay 10s 则设置了每次重试之间的延迟时间为10秒。命令成功拉取了 ubi9 镜像，并返回了镜像的 ID。

另请参阅​

历史​

2017年7月，最初由 Urvashi Mohnani 整理编写。