1podman-pull(1) General Commands Manual podman-pull(1)
2
6 podman-pull - Pull an image from a registry
7
10 podman pull [options] source [source...]
11 podman image pull [options] source [source...]
14 podman pull [options] [transport]name[:tag|@digest]
17 podman image pull [options] [transport]name[:tag|@digest]
20
23 podman pull copies an image from a registry onto the local machine. The
24 command can pull one or more images. If the image reference in the
25 command line argument does not contain a registry, it is referred to as
26 ashort-name reference. If the image is a 'short-name' reference, Podman
27 prompts the user for the specific container registry to pull the image
28 from, if an alias for the short-name has not been specified in the
29 short-name-aliases.conf. If an image tag is not specified, podman pull
30 defaults to the image with the latest tag (if it exists) and pulls it.
31 After the image is pulled, podman prints the full image ID. podman
32 pull can also pull images using a digest podman pull image@digest and
33 can also be used to pull images from archives and local storage using
34 different transports. IMPORTANT: Images are stored in local image
35 storage.
36
39 SOURCE is the location from which the container image is pulled from.
40 It supports all transports from containers-transports(5). If no trans‐
41 port is specified, the input is subject to short-name resolution and
42 the docker (i.e., container registry) transport is used. For remote
43 clients, including Mac and Windows (excluding WSL2) machines, docker is
44 the only supported transport.
45 # Pull from a container registry
48 $ podman pull quay.io/username/myimage
49 # Pull from a container registry with short-name resolution
51 $ podman pull fedora
52 # Pull from a container registry via the docker transport
54 $ podman pull docker://quay.io/username/myimage
55 # Pull from a local directory
57 $ podman pull dir:/tmp/myimage
58 # Pull from a tarball in the docker-archive format
60 $ podman pull docker-archive:/tmp/myimage
61 # Pull from a local docker daemon
63 $ sudo podman pull docker-daemon:docker.io/library/myimage:33
64 # Pull from a tarball in the OCI-archive format
66 $ podman pull oci-archive:/tmp/myimage
67
71 --all-tags, -a
72 All tagged images in the repository are pulled.
73 *IMPORTANT: When using the all-tags flag, Podman does not iterate over
76 the search registries in the containers-registries.conf(5) but always
77 uses docker.io for unqualified image names.*
78 --arch=ARCH
81 Override the architecture, defaults to hosts, of the image to be
82 pulled. For example, arm. Unless overridden, subsequent lookups of the
83 same image in the local storage matches this architecture, regardless
84 of the host.
85 --authfile=path
88 Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
89 ers/auth.json on Linux, and $HOME/.config/containers/auth.json on Win‐
90 dows/macOS. The file is created by podman login. If the authorization
91 state is not found there, $HOME/.docker/config.json is checked, which
92 is set using docker login.
93 Note: There is also the option to override the default path of the au‐
96 thentication file by setting the REGISTRY_AUTH_FILE environment vari‐
97 able. This can be done with export REGISTRY_AUTH_FILE=path.
98 --cert-dir=path
101 Use certificates at path (*.crt, *.cert, *.key) to connect to the reg‐
102 istry. (Default: /etc/containers/certs.d) For details, see containers-
103 certs.d(5). (This option is not available with the remote Podman
104 client, including Mac and Windows (excluding WSL2) machines)
105 --creds=[username[:password]]
108 The [username[:password]] to use to authenticate with the registry, if
109 required. If one or both values are not supplied, a command line
110 prompt appears and the value can be entered. The password is entered
111 without echo.
112 Note that the specified credentials are only used to authenticate
115 against target registries. They are not used for mirrors or when the
116 registry gets rewritten (see containers-registries.conf(5)); to authen‐
117 ticate against those consider using a containers-auth.json(5) file.
118 --decryption-key=key[:passphrase]
121 The [key[:passphrase]] to be used for decryption of images. Key can
122 point to keys and/or certificates. Decryption is tried with all keys.
123 If the key is protected by a passphrase, it is required to be passed in
124 the argument and omitted otherwise.
125 --disable-content-trust
128 This is a Docker-specific option to disable image verification to a
129 container registry and is not supported by Podman. This option is a
130 NOOP and provided solely for scripting compatibility.
131 --help, -h
134 Print the usage statement.
135 --os=OS
138 Override the OS, defaults to hosts, of the image to be pulled. For ex‐
139 ample, windows. Unless overridden, subsequent lookups of the same im‐
140 age in the local storage matches this OS, regardless of the host.
141 --platform=OS/ARCH
144 Specify the platform for selecting the image. (Conflicts with --arch
145 and --os) The --platform option can be used to override the current ar‐
146 chitecture and operating system. Unless overridden, subsequent lookups
147 of the same image in the local storage matches this platform, regard‐
148 less of the host.
149 --quiet, -q
152 Suppress output information when pulling images
153 --tls-verify
156 Require HTTPS and verify certificates when contacting registries (de‐
157 fault: true). If explicitly set to true, TLS verification is used. If
158 set to false, TLS verification is not used. If not specified, TLS ver‐
159 ification is used unless the target registry is listed as an insecure
160 registry in containers-registries.conf(5)
161 --variant=VARIANT
164 Use VARIANT instead of the default architecture variant of the con‐
165 tainer image. Some images can use multiple variants of the arm archi‐
166 tectures, such as arm/v5 and arm/v7.
167
170 short-name-aliases.conf (/var/cache/containers/short-name-aliases.conf,
171 $HOME/.cache/containers/short-name-aliases.conf)
172 When users specify images that do not include the container registry
175 where the image is stored, this is called a short name. The use of un‐
176 qualified-search registries entails an ambiguity as it is unclear from
177 which registry a given image, referenced by a short name, may be pulled
178 from.
179 Using short names is subject to the risk of hitting squatted registry
182 namespaces. If the unqualified-search registries are set to ["public-
183 registry.com", "my-private-registry.com"] an attacker may take over a
184 namespace of public-registry.com such that an image may be pulled from
185 public-registry.com instead of the intended source my-private-reg‐
186 istry.com.
187 While it is highly recommended to always use fully-qualified image ref‐
190 erences, existing deployments using short names may not be easily
191 changed. To circumvent the aforementioned ambiguity, so called short-
192 name aliases can be configured that point to a fully-qualified image
193 reference. Distributions often ship a default shortnames.conf expansion
194 file in /etc/containers/registries.conf.d/ directory. Administrators
195 can use this directory to add their own local short-name expansion
196 files.
197 When pulling an image, if the user does not specify the complete reg‐
200 istry, container engines attempt to expand the short-name into a full
201 name. If the command is executed with a tty, the user is prompted to
202 select a registry from the default list unqualified registries defined
203 in registries.conf. The user's selection is then stored in a cache file
204 to be used in all future short-name expansions. Rootful short-names are
205 stored in /var/cache/containers/short-name-aliases.conf. Rootless
206 short-names are stored in the $HOME/.cache/containers/short-name-
207 aliases.conf file.
208 For more information on short-names, see containers-registries.conf(5)
211 registries.conf (/etc/containers/registries.conf)
214 registries.conf is the configuration file which specifies which con‐
217 tainer registries is consulted when completing image names which do not
218 include a registry or domain portion.
219 NOTE: Use the environment variable TMPDIR to change the temporary stor‐
222 age location of downloaded container images. Podman defaults to use
223 /var/tmp.
224
227 Pull a single image with short name resolution.
228 $ podman pull alpine:latest
231 Resolved "alpine" as an alias (/etc/containers/registries.conf.d/000-shortnames.conf)
232 Trying to pull docker.io/library/alpine:latest...
233 Getting image source signatures
234 Copying blob 5843afab3874 done
235 Copying config d4ff818577 done
236 Writing manifest to image destination
237 Storing signatures
238 d4ff818577bc193b309b355b02ebc9220427090057b54a59e73b79bdfe139b83
239 Pull multiple images with/without short name resolution.
243 podman pull busybox:musl alpine quay.io/libpod/cirros
246 Trying to pull docker.io/library/busybox:musl...
247 Getting image source signatures
248 Copying blob 0c52b060233b [--------------------------------------] 0.0b / 0.0b
249 Copying config 9ad2c435a8 done
250 Writing manifest to image destination
251 Storing signatures
252 9ad2c435a887e3f723654e09b48563de44aa3c7950246b2e9305ec85dd3422db
253 Trying to pull docker.io/library/alpine:latest...
254 Getting image source signatures
255 Copying blob 5843afab3874 [--------------------------------------] 0.0b / 0.0b
256 Copying config d4ff818577 done
257 Writing manifest to image destination
258 Storing signatures
259 d4ff818577bc193b309b355b02ebc9220427090057b54a59e73b79bdfe139b83
260 Trying to pull quay.io/libpod/cirros:latest...
261 Getting image source signatures
262 Copying blob 8da581cc9286 done
263 Copying blob 856628d95d17 done
264 Copying blob f513001ba4ab done
265 Copying config 3c82e4d066 done
266 Writing manifest to image destination
267 Storing signatures
268 3c82e4d066cf6f9e50efaead6e3ff7fddddf5527826afd68e5a969579fc4db4a
269 Pull an image using its digest.
273 $ podman pull alpine@sha256:d7342993700f8cd7aba8496c2d0e57be0666e80b4c441925fc6f9361fa81d10e
276 Trying to pull docker.io/library/alpine@sha256:d7342993700f8cd7aba8496c2d0e57be0666e80b4c441925fc6f9361fa81d10e...
277 Getting image source signatures
278 Copying blob 188c0c94c7c5 done
279 Copying config d6e46aa247 done
280 Writing manifest to image destination
281 Storing signatures
282 d6e46aa2470df1d32034c6707c8041158b652f38d2a9ae3d7ad7e7532d22ebe0
283 Pull an image by specifying an authentication file.
287 $ podman pull --authfile temp-auths/myauths.json docker://docker.io/umohnani/finaltest
290 Trying to pull docker.io/umohnani/finaltest:latest...Getting image source signatures
291 Copying blob sha256:6d987f6f42797d81a318c40d442369ba3dc124883a0964d40b0c8f4f7561d913
292 1.90 MB / 1.90 MB [========================================================] 0s
293 Copying config sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156
294 1.41 KB / 1.41 KB [========================================================] 0s
295 Writing manifest to image destination
296 Storing signatures
297 03290064078cb797f3e0a530e78c20c13dd22a3dd3adf84a5da2127b48df0438
298 Pull an image by authenticating to a registry.
302 $ podman pull --creds testuser:testpassword docker.io/umohnani/finaltest
305 Trying to pull docker.io/umohnani/finaltest:latest...Getting image source signatures
306 Copying blob sha256:6d987f6f42797d81a318c40d442369ba3dc124883a0964d40b0c8f4f7561d913
307 1.90 MB / 1.90 MB [========================================================] 0s
308 Copying config sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156
309 1.41 KB / 1.41 KB [========================================================] 0s
310 Writing manifest to image destination
311 Storing signatures
312 03290064078cb797f3e0a530e78c20c13dd22a3dd3adf84a5da2127b48df0438
313 Pull an image using tls verification.
317 $ podman pull --tls-verify=false --cert-dir image/certs docker.io/umohnani/finaltest
320 Trying to pull docker.io/umohnani/finaltest:latest...Getting image source signatures
321 Copying blob sha256:6d987f6f42797d81a318c40d442369ba3dc124883a0964d40b0c8f4f7561d913
322 1.90 MB / 1.90 MB [========================================================] 0s
323 Copying config sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156
324 1.41 KB / 1.41 KB [========================================================] 0s
325 Writing manifest to image destination
326 Storing signatures
327 03290064078cb797f3e0a530e78c20c13dd22a3dd3adf84a5da2127b48df0438
328 Pull an image by overriding the host architecture.
332 $ podman pull --arch=arm arm32v7/debian:stretch
335 Trying to pull docker.io/arm32v7/debian:stretch...
336 Getting image source signatures
337 Copying blob b531ae4a3925 done
338 Copying config 3cba58dad5 done
339 Writing manifest to image destination
340 Storing signatures
341 3cba58dad5d9b35e755b48b634acb3fdd185ab1c996ac11510cc72c17780e13c
342
346 podman(1), podman-push(1), podman-login(1), containers-certs.d(5), con‐
347 tainers-registries.conf(5), containers-transports(5)
348
351 July 2017, Originally compiled by Urvashi Mohnani umohnani@redhat.com
352 ⟨mailto:umohnani@redhat.com⟩
353 podman-pull(1)