NAME¶ 名称
podman-pull - Pull an image from a registry
podman-pull - 从注册表中拉取镜像
SYNOPSIS¶ 概要
podman pull [options] source [source…]
podman pull [选项] 源 [源…]
podman image pull [options] source [source…]
podman image pull [选项] 源 [源…]
podman pull [options] [transport]name[:tag|@digest]
podman image pull [options] [transport]name[:tag|@digest]
DESCRIPTION¶ 描述
podman pull copies an image from a registry onto the local machine. The command can pull one or more images. If the image reference in the command line argument does not contain a registry, it is referred to as ashort-name reference. If the image is a ‘short-name’ reference, Podman prompts the user for the specific container registry to pull the image from, if an alias for the short-name has not been specified in the short-name-aliases.conf. If an image tag is not specified, podman pull defaults to the image with the latest tag (if it exists) and pulls it. After the image is pulled, podman prints the full image ID. podman pull can also pull images using a digest podman pull image@digest and can also be used to pull images from archives and local storage using different transports.
IMPORTANT: Images are stored in local image storage.
podman pull 将镜像从注册表复制到本地计算机。该命令可以拉取一个或多个镜像。如果命令行参数中的镜像引用不包含注册表，则称为 short-name 引用。如果镜像是“短名称”引用，则 Podman 会提示用户从特定容器注册表中拉取镜像，如果短名称的别名未在 short-name-aliases.conf 中指定。如果未指定镜像标签，podman pull 默认拉取具有最新标签的镜像（如果存在）并拉取它。在拉取镜像后，podman 会打印完整的镜像 ID。podman pull 还可以使用摘要 podman pull image@digest 拉取镜像，并且还可以使用不同的传输方式从存档和本地存储中拉取镜像。重要提示：镜像存储在本地镜像存储中。
SOURCE¶ 源
SOURCE is the location from which the container image is pulled from. It supports all transports from containers-transports(5). If no transport is specified, the input is subject to short-name resolution and the docker (i.e., container registry) transport is used. For remote clients, including Mac and Windows (excluding WSL2) machines, docker is the only supported transport.
源是从中拉取容器镜像的位置。它支持来自 containers-transports(5) 的所有传输。如果未指定传输，则输入将受到短名称解析的影响，并使用 docker （即容器注册表）传输。对于远程客户端，包括 Mac 和 Windows（不包括 WSL2）机器， docker 是唯一支持的传输。
# Pull from a container registry
$ podman pull quay.io/username/myimage
# Pull from a container registry with short-name resolution
$ podman pull fedora
# Pull from a container registry via the docker transport
$ podman pull docker://quay.io/username/myimage
# Pull from a local directory
$ podman pull dir:/tmp/myimage
# Pull from a tarball in the docker-archive format
$ podman pull docker-archive:/tmp/myimage
# Pull from a local docker daemon
$ sudo podman pull docker-daemon:docker.io/library/myimage:33
# Pull from a tarball in the OCI-archive format
$ podman pull oci-archive:/tmp/myimage
OPTIONS¶ 选项
--arch=ARCH¶
Override the architecture, defaults to hosts, of the image to be pulled. For example, arm.
Unless overridden, subsequent lookups of the same image in the local storage matches this architecture, regardless of the host.
覆盖要拉取的镜像的架构，默认为主机的架构。例如， arm 。除非被覆盖，否则在本地存储中对相同镜像的后续查找将匹配此架构，而不考虑主机。
--authfile=path¶
Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/containers/auth.json on Linux, and $HOME/.config/containers/auth.json on Windows/macOS.
The file is created by podman login. If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using docker login.
认证文件的路径。在 Linux 上默认为 ${XDG_RUNTIME_DIR}/containers/auth.json ，在 Windows/macOS 上默认为 $HOME/.config/containers/auth.json 。该文件由 podman login 创建。如果授权状态未在那里找到，则会检查 $HOME/.docker/config.json ，该值是使用 docker login 设置的。
Note: There is also the option to override the default path of the authentication file by setting the REGISTRY_AUTH_FILE environment variable. This can be done with export REGISTRY_AUTH_FILE=path.
注意：还有一种选择，可以通过设置 REGISTRY_AUTH_FILE 环境变量来覆盖认证文件的默认路径。可以通过 export REGISTRY_AUTH_FILE=path 来实现。
--cert-dir=path¶
Use certificates at path (*.crt, *.cert, *.key) to connect to the registry. (Default: /etc/containers/certs.d)
For details, see containers-certs.d(5).
(This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines)
使用证书路径（*.crt, *.cert, *.key）连接到注册表。 （默认值：/etc/containers/certs.d）有关详细信息，请参阅 containers-certs.d(5)。 （此选项不适用于远程 Podman 客户端，包括 Mac 和 Windows（不包括 WSL2）机器）
--creds=[username[:password]]¶
--creds=[用户名[:密码]] ¶
The [username[:password]] to use to authenticate with the registry, if required.
If one or both values are not supplied, a command line prompt appears and the
value can be entered. The password is entered without echo.
如果需要，用于与注册表进行身份验证的[用户名[:密码]]。如果一个或两个值未提供，将出现命令行提示，并可以输入该值。密码输入时不会显示。
Note that the specified credentials are only used to authenticate against
target registries. They are not used for mirrors or when the registry gets
rewritten (see containers-registries.conf(5)); to authenticate against those
consider using a containers-auth.json(5) file.
请注意，指定的凭据仅用于对目标注册表进行身份验证。它们不用于镜像或注册表被重写时（请参阅 containers-registries.conf(5) ）；要对其进行身份验证，请考虑使用 containers-auth.json(5) 文件。
--decryption-key=key[:passphrase]¶
The [key[:passphrase]] to be used for decryption of images. Key can point to keys and/or certificates. Decryption is tried with all keys. If the key is protected by a passphrase, it is required to be passed in the argument and omitted otherwise.
用于解密图像的密钥[:密码]。密钥可以指向密钥和/或证书。尝试使用所有密钥进行解密。如果密钥受密码保护，则需要在参数中传递密码，否则应省略。
--disable-content-trust¶
This is a Docker-specific option to disable image verification to a container
registry and is not supported by Podman. This option is a NOOP and provided
solely for scripting compatibility.
这是一个 Docker 特定选项，用于禁用对容器注册表的镜像验证，不受 Podman 支持。此选项是一个 NOOP，并且仅用于脚本兼容性。
--help, -h¶ --help，-h ¶
Print the usage statement.
打印用法说明。
--os=OS¶ --os=操作系统 ¶
Override the OS, defaults to hosts, of the image to be pulled. For example, windows.
Unless overridden, subsequent lookups of the same image in the local storage matches this OS, regardless of the host.
覆盖要拉取的镜像的操作系统，默认为主机。例如， windows 。除非被覆盖，否则在本地存储中对相同镜像的后续查找将匹配此操作系统，而不考虑主机。
--platform=OS/ARCH¶
Specify the platform for selecting the image. (Conflicts with --arch and --os)
The --platform option can be used to override the current architecture and operating system.
Unless overridden, subsequent lookups of the same image in the local storage matches this platform, regardless of the host.
指定用于选择镜像的平台。(与 --arch 和 --os 冲突) --platform 选项可用于覆盖当前的架构和操作系统。除非被覆盖，否则在本地存储中对相同镜像的后续查找将匹配此平台，而不考虑主机。
--quiet, -q¶
Suppress output information when pulling images
在拉取图像时抑制输出信息。
--retry=attempts¶
Number of times to retry pulling or pushing images between the registry and
local storage in case of failure. Default is 3.
在发生失败时，重试在注册表和本地存储之间拉取或推送镜像的次数。默认值为 3。
--retry-delay=duration¶ --retry-delay=持续时间 ¶
Duration of delay between retry attempts when pulling or pushing images between
the registry and local storage in case of failure. The default is to start at two seconds and then exponentially back off. The delay is used when this value is set, and no exponential back off occurs.
在发生失败时，拉取或推送镜像在注册表和本地存储之间重试尝试之间的延迟持续时间。默认值是从两秒开始，然后指数级地减少。当设置了此值且没有指数级减少时，将使用延迟。
--tls-verify¶
Require HTTPS and verify certificates when contacting registries (default: true).
If explicitly set to true, TLS verification is used.
If set to false, TLS verification is not used.
If not specified, TLS verification is used unless the target registry
is listed as an insecure registry in containers-registries.conf(5)
在联系注册表时需要 HTTPS 并验证证书（默认值为 true）。如果显式设置为 true，则使用 TLS 验证。如果设置为 false，则不使用 TLS 验证。如果未指定，则除非目标注册表在 containers-registries.conf(5) 中被列为不安全注册表，否则将使用 TLS 验证。
--variant=VARIANT¶
Use VARIANT instead of the default architecture variant of the container image. Some images can use multiple variants of the arm architectures, such as arm/v5 and arm/v7.
使用 VARIANT 替代容器镜像的默认架构变体。某些镜像可以使用 arm 架构的多个变体，例如 arm/v5 和 arm/v7。
FILES¶ 文件 ¶
short-name-aliases.conf (/var/cache/containers/short-name-aliases.conf, $HOME/.cache/containers/short-name-aliases.conf)
短名称别名.conf ( /var/cache/containers/short-name-aliases.conf , $HOME/.cache/containers/short-name-aliases.conf )
When users specify images that do not include the container registry where the
image is stored, this is called a short name. The use of unqualified-search registries entails an ambiguity as it is unclear from which registry a given image, referenced by a short name, may be pulled from.
当用户指定不包括存储图像的容器注册表的图像时，这被称为短名称。 使用未经合格搜索注册表会导致歧义，因为不清楚通过短名称引用的给定图像可能从哪个注册表中拉取。
Using short names is subject to the risk of hitting squatted registry namespaces. If the unqualified-search registries are set to [“public-registry.com”, “my-private-registry.com”] an attacker may take over a namespace of public-registry.com such that an image may be pulled from public-registry.com instead of the intended source my-private-registry.com.
使用短名称存在命中被占用注册表命名空间的风险。 如果未经合格搜索注册表设置为 [“public-registry.com”, “my-private-registry.com”]，攻击者可能接管 public-registry.com 的命名空间，以便从 public-registry.com 而不是预期的源 my-private-registry.com 拉取图像。
While it is highly recommended to always use fully-qualified image references, existing deployments using short names may not be easily changed. To circumvent the aforementioned ambiguity, so called short-name aliases can be configured that point to a fully-qualified image reference. Distributions often ship a default shortnames.conf expansion file in /etc/containers/registries.conf.d/ directory. Administrators can use this directory to add their own local short-name expansion files.
虽然强烈建议始终使用完全合格的镜像引用，但使用短名称的现有部署可能不容易更改。为了避免上述的歧义，可以配置所谓的短名称别名，指向完全合格的镜像引用。发行版通常在 /etc/containers/registries.conf.d/ 目录中提供一个默认的 shortnames.conf 扩展文件。管理员可以使用此目录添加自己的本地短名称扩展文件。
When pulling an image, if the user does not specify the complete registry, container engines attempt to expand the short-name into a full name. If the command is executed with a tty, the user is prompted to select a registry from the
default list unqualified registries defined in registries.conf. The user’s selection is then stored in a cache file to be used in all future short-name expansions. Rootful short-names are stored in /var/cache/containers/short-name-aliases.conf. Rootless short-names are stored in the $HOME/.cache/containers/short-name-aliases.conf file.
在拉取镜像时，如果用户没有指定完整的注册表，容器引擎会尝试将短名称扩展为完整名称。如果使用 tty 执行命令，则会提示用户从 registries.conf 中定义的默认列表中选择一个注册表。然后将用户的选择存储在缓存文件中，以便在所有未来的短名称扩展中使用。Rootful 短名称存储在 /var/cache/containers/short-name-aliases.conf 中。Rootless 短名称存储在 $HOME/.cache/containers/short-name-aliases.conf 文件中。
For more information on short-names, see containers-registries.conf(5)
有关短名称的更多信息，请参见 containers-registries.conf(5)
registries.conf (/etc/containers/registries.conf)
registries.conf is the configuration file which specifies which container registries is consulted when completing image names which do not include a registry or domain portion.
registries.conf 是配置文件，指定在完成不包括注册表或域部分的图像名称时要查询哪些容器注册表。
NOTE: Use the environment variable TMPDIR to change the temporary storage location of downloaded container images. Podman defaults to use /var/tmp.
注意：使用环境变量 TMPDIR 来更改下载容器镜像的临时存储位置。Podman 默认使用 /var/tmp 。
EXAMPLES¶ 示例
Pull a single image with short name resolution.
使用短名称解析拉取单个镜像。
$ podman pull alpine:latest
Resolved "alpine" as an alias (/etc/containers/registries.conf.d/000-shortnames.conf)
Trying to pull docker.io/library/alpine:latest...
Getting image source signatures
Copying blob 5843afab3874 done
Copying config d4ff818577 done
Writing manifest to image destination
Storing signatures
d4ff818577bc193b309b355b02ebc9220427090057b54a59e73b79bdfe139b83
Pull multiple images with/without short name resolution.
使用/不使用短名称解析拉取多个镜像。
podman pull busybox:musl alpine quay.io/libpod/cirros
Trying to pull docker.io/library/busybox:musl...
Getting image source signatures
Copying blob 0c52b060233b [--------------------------------------] 0.0b / 0.0b
Copying config 9ad2c435a8 done
Writing manifest to image destination
Storing signatures
9ad2c435a887e3f723654e09b48563de44aa3c7950246b2e9305ec85dd3422db
Trying to pull docker.io/library/alpine:latest...
Getting image source signatures
Copying blob 5843afab3874 [--------------------------------------] 0.0b / 0.0b
Copying config d4ff818577 done
Writing manifest to image destination
Storing signatures
d4ff818577bc193b309b355b02ebc9220427090057b54a59e73b79bdfe139b83
Trying to pull quay.io/libpod/cirros:latest...
Getting image source signatures
Copying blob 8da581cc9286 done
Copying blob 856628d95d17 done
Copying blob f513001ba4ab done
Copying config 3c82e4d066 done
Writing manifest to image destination
Storing signatures
3c82e4d066cf6f9e50efaead6e3ff7fddddf5527826afd68e5a969579fc4db4a
Pull an image using its digest.
使用摘要拉取镜像。
$ podman pull alpine@sha256:d7342993700f8cd7aba8496c2d0e57be0666e80b4c441925fc6f9361fa81d10e
Trying to pull docker.io/library/alpine@sha256:d7342993700f8cd7aba8496c2d0e57be0666e80b4c441925fc6f9361fa81d10e...
Getting image source signatures
Copying blob 188c0c94c7c5 done
Copying config d6e46aa247 done
Writing manifest to image destination
Storing signatures
d6e46aa2470df1d32034c6707c8041158b652f38d2a9ae3d7ad7e7532d22ebe0
Pull an image by specifying an authentication file.
通过指定认证文件拉取镜像。
$ podman pull --authfile temp-auths/myauths.json docker://docker.io/umohnani/finaltest
Trying to pull docker.io/umohnani/finaltest:latest...Getting image source signatures
Copying blob sha256:6d987f6f42797d81a318c40d442369ba3dc124883a0964d40b0c8f4f7561d913
1.90 MB / 1.90 MB [========================================================] 0s
Copying config sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156
1.41 KB / 1.41 KB [========================================================] 0s
Writing manifest to image destination
Storing signatures
03290064078cb797f3e0a530e78c20c13dd22a3dd3adf84a5da2127b48df0438
Pull an image by authenticating to a registry.
通过向注册表进行身份验证来拉取镜像。
$ podman pull --creds testuser:testpassword docker.io/umohnani/finaltest
Trying to pull docker.io/umohnani/finaltest:latest...Getting image source signatures
Copying blob sha256:6d987f6f42797d81a318c40d442369ba3dc124883a0964d40b0c8f4f7561d913
1.90 MB / 1.90 MB [========================================================] 0s
Copying config sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156
1.41 KB / 1.41 KB [========================================================] 0s
Writing manifest to image destination
Storing signatures
03290064078cb797f3e0a530e78c20c13dd22a3dd3adf84a5da2127b48df0438
Pull an image using tls verification.
使用 TLS 验证拉取镜像。
$ podman pull --tls-verify=false --cert-dir image/certs docker.io/umohnani/finaltest
Trying to pull docker.io/umohnani/finaltest:latest...Getting image source signatures
Copying blob sha256:6d987f6f42797d81a318c40d442369ba3dc124883a0964d40b0c8f4f7561d913
1.90 MB / 1.90 MB [========================================================] 0s
Copying config sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156
1.41 KB / 1.41 KB [========================================================] 0s
Writing manifest to image destination
Storing signatures
03290064078cb797f3e0a530e78c20c13dd22a3dd3adf84a5da2127b48df0438
Pull an image by overriding the host architecture.
通过覆盖主机架构拉取镜像。
$ podman pull --arch=arm arm32v7/debian:stretch
Trying to pull docker.io/arm32v7/debian:stretch...
Getting image source signatures
Copying blob b531ae4a3925 done
Copying config 3cba58dad5 done
Writing manifest to image destination
Storing signatures
3cba58dad5d9b35e755b48b634acb3fdd185ab1c996ac11510cc72c17780e13c
Pull an image with up to 6 retries, delaying 10 seconds between retries in quet mode.
在安静模式下，最多重试 6 次，每次重试之间延迟 10 秒拉取镜像。
$ podman --remote pull -q --retry 6 --retry-delay 10s ubi9
4d6addf62a90e392ff6d3f470259eb5667eab5b9a8e03d20b41d0ab910f92170
SEE ALSO¶ 参见 ¶
podman(1), podman-push(1), podman-login(1), containers-certs.d(5), containers-registries.conf(5), containers-transports(5)
HISTORY¶ 历史 ¶
July 2017, Originally compiled by Urvashi Mohnani umohnani@redhat.com
2017 年 7 月，最初由 Urvashi Mohnani umohnani@redhat.com 编写