1podman-pull(1)()                                              podman-pull(1)()
2
3
4

NAME

6       podman-pull - Pull an image from a registry
7
8

SYNOPSIS

10       podman pull [options] source [source...]
11
12
13       podman image pull [options] source [source...]
14
15
16       podman pull [options] [transport]name[:tag|@digest]
17
18
19       podman image pull [options] [transport]name[:tag|@digest]
20
21

DESCRIPTION

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       will  prompt  the  user for the specific container registry to pull the
28       image from, if an alias for the short-name has not  been  specified  in
29       the  short-name-aliases.conf.  If an image tag is not specified, podman
30       pull defaults to the image with the latest tag (if it exists) and pulls
31       it.  After  the  image  is pulled, podman will print the full image ID.
32       podman pull can also pull images using a digest podman  pull  image@di‐
33       gest  and can also be used to pull images from archives and local stor‐
34       age using different transports.  IMPORTANT: Images are stored in  local
35       image storage.
36
37

SOURCE

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
46
47              # Pull from a container registry
48              $ podman pull quay.io/username/myimage
49
50              # Pull from a container registry with short-name resolution
51              $ podman pull fedora
52
53              # Pull from a container registry via the docker transport
54              $ podman pull docker://quay.io/username/myimage
55
56              # Pull from a local directory
57              $ podman pull dir:/tmp/myimage
58
59              # Pull from a tarball in the docker-archive format
60              $ podman pull docker-archive:/tmp/myimage
61
62              # Pull from a local docker daemon
63              $ sudo podman pull docker-daemon:docker.io/library/myimage:33
64
65              # Pull from a tarball in the OCI-archive format
66              $ podman pull oci-archive:/tmp/myimage
67
68
69

OPTIONS

71   --all-tags
72       All tagged images in the repository will be pulled.
73
74
75       *IMPORTANT: When using the all-tags flag, Podman will not iterate  over
76       the search registries in the containers-registries.conf(5) but will al‐
77       ways use docker.io for unqualified image names.*
78
79
80   --arch=ARCH
81       Override the architecture, defaults  to  hosts,  of  the  image  to  be
82       pulled. For example, arm.
83
84
85   --authfile=path
86       Path  of  the  authentication  file.  If the authorization state is not
87       found there, $HOME/.docker/config.json is checked, which is  set  using
88       docker login.
89
90
91       Default  is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set us‐
92       ing podman login.
93
94
95       IMPORTANT: The default path of the authentication file can be overwrit‐
96       ten  by  setting  the REGISTRY\_AUTH\_FILE environment variable. export
97       REGISTRY_AUTH_FILE=path
98
99
100   --cert-dir=path
101       Use certificates at path (*.crt, *.cert, *.key) to connect to the  reg‐
102       istry.  (Default:  /etc/containers/certs.d) Please refer to containers-
103       certs.d(5) for details. (This option is not available with  the  remote
104       Podman client, including Mac and Windows (excluding WSL2) machines)
105
106
107   --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  will  appear and the value can be entered.  The password is en‐
111       tered without echo.
112
113
114   --disable-content-trust
115       This is a Docker specific option to disable  image  verification  to  a
116       Docker  registry  and  is not supported by Podman.  This flag is a NOOP
117       and provided solely for scripting compatibility.
118
119
120   --help, -h
121       Print the usage statement.
122
123
124   --os=OS
125       Override the OS, defaults to hosts, of the image to be pulled. For  ex‐
126       ample, windows.
127
128
129   --platform=OS/ARCH
130       Specify the platform for selecting the image. The --platform option can
131       be used to override the current architecture and operating system.
132
133
134       IMPORTANT: Conflicts with --arch and --os
135
136
137   --quiet, -q
138       Suppress output information when pulling images
139
140
141   --tls-verify
142       Require HTTPS and verify certificates when contacting  registries  (de‐
143       fault:  true). If explicitly set to true, then TLS verification will be
144       used. If set to false, then TLS verification will not be used.  If  not
145       specified,  TLS verification will be used unless the target registry is
146       listed as an insecure registry in registries.conf.
147
148
149   --variant=VARIANT
150       Use VARIANT instead of the default architecture  variant  of  the  con‐
151       tainer  image.  Some images can use multiple variants of the arm archi‐
152       tectures, such as arm/v5 and arm/v7.
153
154

FILES

156       short-name-aliases.conf (/var/cache/containers/short-name-aliases.conf,
157       $HOME/.cache/containers/short-name-aliases.conf)
158
159
160       When  users  specify  images that do not include the container registry
161       where the image is stored, this is called a short name. The use of  un‐
162       qualified-search  registries entails an ambiguity as it is unclear from
163       which registry a given image, referenced by a short name, may be pulled
164       from.
165
166
167       Using  short  names is subject to the risk of hitting squatted registry
168       namespaces. If the unqualified-search registries are set  to  ["public-
169       registry.com",   "my-private-registry.com"] an attacker may take over a
170       namespace of public-registry.com such that an image may be pulled  from
171       public-registry.com  instead  of  the  intended  source my-private-reg‐
172       istry.com.
173
174
175       While it is highly recommended to always use fully-qualified image ref‐
176       erences,  existing  deployments  using  short  names  may not be easily
177       changed. To circumvent the aforementioned ambiguity, so  called  short-
178       name  aliases  can  be configured that point to a fully-qualified image
179       reference. Distributions often ship a default shortnames.conf expansion
180       file  in  /etc/containers/registries.conf.d/  directory. Administrators
181       can use this directory to add  their  own  local  short-name  expansion
182       files.
183
184
185       When  pulling  an image, if the user does not specify the complete reg‐
186       istry, container engines attempt to expand the short-name into  a  full
187       name.  If the command is executed with a tty, the user will be prompted
188       to select a registry from the default list unqualified  registries  de‐
189       fined  in  registries.conf.  The  user's  selection is then stored in a
190       cache file to be used in  all  future  short-name  expansions.  Rootful
191       short-names    are    stored    in    /var/cache/containers/short-name-
192       aliases.conf. Rootless short-names are stored in the  $HOME/.cache/con‐
193       tainers/short-name-aliases.conf file.
194
195
196       For more information on short-names, see containers-registries.conf(5)
197
198
199       registries.conf (/etc/containers/registries.conf)
200
201
202       registries.conf  is  the  configuration file which specifies which con‐
203       tainer registries should be consulted when completing image names which
204       do not include a registry or domain portion.
205
206
207       NOTE: Use the environment variable TMPDIR to change the temporary stor‐
208       age location of downloaded container images.  Podman  defaults  to  use
209       /var/tmp.
210
211

EXAMPLES

213       Pull a single image with short name resolution.
214
215
216              $ podman pull alpine:latest
217              Resolved "alpine" as an alias (/etc/containers/registries.conf.d/000-shortnames.conf)
218              Trying to pull docker.io/library/alpine:latest...
219              Getting image source signatures
220              Copying blob 5843afab3874 done
221              Copying config d4ff818577 done
222              Writing manifest to image destination
223              Storing signatures
224              d4ff818577bc193b309b355b02ebc9220427090057b54a59e73b79bdfe139b83
225
226
227
228       Pull multiple images with/without short name resolution.
229
230
231              podman pull busybox:musl alpine quay.io/libpod/cirros
232              Trying to pull docker.io/library/busybox:musl...
233              Getting image source signatures
234              Copying blob 0c52b060233b [--------------------------------------] 0.0b / 0.0b
235              Copying config 9ad2c435a8 done
236              Writing manifest to image destination
237              Storing signatures
238              9ad2c435a887e3f723654e09b48563de44aa3c7950246b2e9305ec85dd3422db
239              Trying to pull docker.io/library/alpine:latest...
240              Getting image source signatures
241              Copying blob 5843afab3874 [--------------------------------------] 0.0b / 0.0b
242              Copying config d4ff818577 done
243              Writing manifest to image destination
244              Storing signatures
245              d4ff818577bc193b309b355b02ebc9220427090057b54a59e73b79bdfe139b83
246              Trying to pull quay.io/libpod/cirros:latest...
247              Getting image source signatures
248              Copying blob 8da581cc9286 done
249              Copying blob 856628d95d17 done
250              Copying blob f513001ba4ab done
251              Copying config 3c82e4d066 done
252              Writing manifest to image destination
253              Storing signatures
254              3c82e4d066cf6f9e50efaead6e3ff7fddddf5527826afd68e5a969579fc4db4a
255
256
257
258       Pull an image using its digest.
259
260
261              $ podman pull alpine@sha256:d7342993700f8cd7aba8496c2d0e57be0666e80b4c441925fc6f9361fa81d10e
262              Trying to pull docker.io/library/alpine@sha256:d7342993700f8cd7aba8496c2d0e57be0666e80b4c441925fc6f9361fa81d10e...
263              Getting image source signatures
264              Copying blob 188c0c94c7c5 done
265              Copying config d6e46aa247 done
266              Writing manifest to image destination
267              Storing signatures
268              d6e46aa2470df1d32034c6707c8041158b652f38d2a9ae3d7ad7e7532d22ebe0
269
270
271
272       Pull an image by specifying an authentication file.
273
274
275              $ podman pull --authfile temp-auths/myauths.json docker://docker.io/umohnani/finaltest
276              Trying to pull docker.io/umohnani/finaltest:latest...Getting image source signatures
277              Copying blob sha256:6d987f6f42797d81a318c40d442369ba3dc124883a0964d40b0c8f4f7561d913
278               1.90 MB / 1.90 MB [========================================================] 0s
279              Copying config sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156
280               1.41 KB / 1.41 KB [========================================================] 0s
281              Writing manifest to image destination
282              Storing signatures
283              03290064078cb797f3e0a530e78c20c13dd22a3dd3adf84a5da2127b48df0438
284
285
286
287       Pull an image by authenticating to a registry.
288
289
290              $ podman pull --creds testuser:testpassword docker.io/umohnani/finaltest
291              Trying to pull docker.io/umohnani/finaltest:latest...Getting image source signatures
292              Copying blob sha256:6d987f6f42797d81a318c40d442369ba3dc124883a0964d40b0c8f4f7561d913
293               1.90 MB / 1.90 MB [========================================================] 0s
294              Copying config sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156
295               1.41 KB / 1.41 KB [========================================================] 0s
296              Writing manifest to image destination
297              Storing signatures
298              03290064078cb797f3e0a530e78c20c13dd22a3dd3adf84a5da2127b48df0438
299
300
301
302       Pull an image using tls verification.
303
304
305              $ podman pull --tls-verify=false --cert-dir image/certs docker.io/umohnani/finaltest
306              Trying to pull docker.io/umohnani/finaltest:latest...Getting image source signatures
307              Copying blob sha256:6d987f6f42797d81a318c40d442369ba3dc124883a0964d40b0c8f4f7561d913
308               1.90 MB / 1.90 MB [========================================================] 0s
309              Copying config sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156
310               1.41 KB / 1.41 KB [========================================================] 0s
311              Writing manifest to image destination
312              Storing signatures
313              03290064078cb797f3e0a530e78c20c13dd22a3dd3adf84a5da2127b48df0438
314
315
316
317       Pull an image by overriding the host architecture.
318
319
320              $ podman pull --arch=arm arm32v7/debian:stretch
321              Trying to pull docker.io/arm32v7/debian:stretch...
322              Getting image source signatures
323              Copying blob b531ae4a3925 done
324              Copying config 3cba58dad5 done
325              Writing manifest to image destination
326              Storing signatures
327              3cba58dad5d9b35e755b48b634acb3fdd185ab1c996ac11510cc72c17780e13c
328
329
330

SEE ALSO

332       podman(1), podman-push(1), podman-login(1), containers-certs.d(5), con‐
333       tainers-registries.conf(5), containers-transports(5)
334
335

HISTORY

337       July 2017, Originally compiled by Urvashi  Mohnani  umohnani@redhat.com
338       ⟨mailto:umohnani@redhat.com⟩
339
340
341
342                                                              podman-pull(1)()
Impressum