1. docker
  2. Commit 32eff909b4d3072524041fffc9d43efe87d2116f
Browse code

Update Docker pull examples

The old examples no longer worked due to changes in
the client and Docker Hub.

This updates the "docker pull" documentation and
adds more examples and explanation of the features.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

Sebastiaan van Stijn authored on 2016/03/04 23:58:07
Showing 2 changed files
docs/reference/commandline/pull.md
History View file @ 32eff90
... ... 
@@ -24,31 +24,203 @@ Most of your images will be created on top of a base image from the
24 24 
 [Docker Hub](https://hub.docker.com) contains many pre-built images that you
25 25 
 can `pull` and try without needing to define and configure your own.
26 26
27 
-It is also possible to manually specify the path of a registry to pull from.
28 
-For example, if you have set up a local registry, you can specify its path to
29 
-pull from it. A repository path is similar to a URL, but does not contain
30 
-a protocol specifier (`https://`, for example).
31 
-
32 27 
 To download a particular image, or set of images (i.e., a repository),
33 
-use `docker pull`:
34 
-
35 
-    $ docker pull debian
36 
-    # will pull the debian:latest image and its intermediate layers
37 
-    $ docker pull debian:testing
38 
-    # will pull the image named debian:testing and any intermediate
39 
-    # layers it is based on.
40 
-    $ docker pull debian@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf
41 
-    # will pull the image from the debian repository with the digest
42 
-    # sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf
43 
-    # and any intermediate layers it is based on.
44 
-    # (Typically the empty `scratch` image, a MAINTAINER layer,
45 
-    # and the un-tarred base).
46 
-    $ docker pull --all-tags centos
47 
-    # will pull all the images from the centos repository
48 
-    $ docker pull registry.hub.docker.com/debian
49 
-    # manually specifies the path to the default Docker registry. This could
50 
-    # be replaced with the path to a local registry to pull from another source.
51 
-    # sudo docker pull myhub.com:8080/test-image
28 
+use `docker pull`.
29 
+
30 
+## Examples
31 
+
32 
+### Pull an image from Docker Hub
33 
+
34 
+To download a particular image, or set of images (i.e., a repository), use
35 
+`docker pull`. If no tag is provided, Docker Engine uses the `:latest` tag as a
36 
+default. This command pulls the `debian:latest` image:
37 
+
38 
+```bash
39 
+$ docker pull debian
40 
+
41 
+Using default tag: latest
42 
+latest: Pulling from library/debian
43 
+fdd5d7827f33: Pull complete
44 
+a3ed95caeb02: Pull complete
45 
+Digest: sha256:e7d38b3517548a1c71e41bffe9c8ae6d6d29546ce46bf62159837aad072c90aa
46 
+Status: Downloaded newer image for debian:latest
47 
+```
48 
+
49 
+Docker images can consist of multiple layers. In the example above, the image
50 
+consists of two layers; `fdd5d7827f33` and `a3ed95caeb02`.
51 
+
52 
+Layers can be reused by images. For example, the `debian:jessie` image shares
53 
+both layers with `debian:latest`. Pulling the `debian:jessie` image therefore
54 
+only pulls its metadata, but not its layers, because all layers are already
55 
+present locally:
56 
+
57 
+```bash
58 
+$ docker pull debian:jessie
59 
+
60 
+jessie: Pulling from library/debian
61 
+fdd5d7827f33: Already exists
62 
+a3ed95caeb02: Already exists
63 
+Digest: sha256:a9c958be96d7d40df920e7041608f2f017af81800ca5ad23e327bc402626b58e
64 
+Status: Downloaded newer image for debian:jessie
65 
+```
66 
+
67 
+To see which images are present locally, use the [`docker images`](images.md)
68 
+command:
69 
+
70 
+```bash
71 
+$ docker images
72 
+
73 
+REPOSITORY   TAG      IMAGE ID        CREATED      SIZE
74 
+debian       jessie   f50f9524513f    5 days ago   125.1 MB
75 
+debian       latest   f50f9524513f    5 days ago   125.1 MB
76 
+```
77 
+
78 
+Docker uses a content-addressable image store, and the image ID is a SHA256
79 
+digest covering the image's configuration and layers. In the example above,
80 
+`debian:jessie` and `debian:latest` have the same image ID because they are
81 
+actually the *same* image tagged with different names. Because they are the
82 
+same image, their layers are stored only once and do not consume extra disk
83 
+space.
84 
+
85 
+For more information about images, layers, and the content-addressable store,
86 
+refer to [understand images, containers, and storage drivers](../../userguide/storagedriver/imagesandcontainers.md).
87 
+
88 
+
89 
+## Pull an image by digest (immutable identifier)
90 
+
91 
+So far, you've pulled images by their name (and "tag"). Using names and tags is
92 
+a convenient way to work with images. When using tags, you can `docker pull` an
93 
+image again to make sure you have the most up-to-date version of that image.
94 
+For example, `docker pull ubuntu:14.04` pulls the latest version of the Ubuntu
95 
+14.04 image.
96 
+
97 
+In some cases you don't want images to be updated to newer versions, but prefer
98 
+to use a fixed version of an image. Docker enables you to pull an image by its
99 
+*digest*. When pulling an image by digest, you specify *exactly* which version
100 
+of an image to pull. Doing so, allows you to "pin" an image to that version,
101 
+and guarantee that the image you're using is always the same.
102 
+
103 
+To know the digest of an image, pull the image first. Let's pull the latest
104 
+`ubuntu:14.04` image from Docker Hub:
105 
+
106 
+```bash
107 
+$ docker pull ubuntu:14.04
108 
+
109 
+14.04: Pulling from library/ubuntu
110 
+5a132a7e7af1: Pull complete
111 
+fd2731e4c50c: Pull complete
112 
+28a2f68d1120: Pull complete
113 
+a3ed95caeb02: Pull complete
114 
+Digest: sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2
115 
+Status: Downloaded newer image for ubuntu:14.04
116 
+```
117 
+
118 
+Docker prints the digest of the image after the pull has finished. In the example
119 
+above, the digest of the image is:
120 
+
121 
+    sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2
122 
+
123 
+Docker also prints the digest of an image when *pushing* to a registry. This
124 
+may be useful if you want to pin to a version of the image you just pushed.
125 
+
126 
+A digest takes the place of the tag when pulling an image, for example, to
127 
+pull the above image by digest, run the following command:
128 
+
129 
+```bash
130 
+$ docker pull ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2
131 
+
132 
+sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2: Pulling from library/ubuntu
133 
+5a132a7e7af1: Already exists
134 
+fd2731e4c50c: Already exists
135 
+28a2f68d1120: Already exists
136 
+a3ed95caeb02: Already exists
137 
+Digest: sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2
138 
+Status: Downloaded newer image for ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2
139 
+```
140 
+
141 
+Digest can also be used in the `FROM` of a Dockerfile, for example:
142 
+
143 
+```Dockerfile
144 
+FROM ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2
145 
+MAINTAINER some maintainer <maintainer@example.com>
146 
+```
147 
+
148 
+> **Note**: Using this feature "pins" an image to a specific version in time.
149 
+> Docker will therefore not pull updated versions of an image, which may include
150 
+> security updates. If you want to pull an updated image, you need to change the
151 
+> digest accordingly.
152 
+
153 
+
154 
+## Pulling from a different registry
155 
+
156 
+By default, `docker pull` pulls images from Docker Hub. It is also possible to
157 
+manually specify the path of a registry to pull from. For example, if you have
158 
+set up a local registry, you can specify its path to pull from it. A registry
159 
+path is similar to a URL, but does not contain a protocol specifier (`https://`).
160 
+
161 
+The following command pulls the `testing/test-image` image from a local registry
162 
+listening on port 5000 (`myregistry.local:5000`):
163 
+
164 
+```bash
165 
+$ docker pull myregistry.local:5000/testing/test-image
166 
+```
167 
+
168 
+Docker uses the `https://` protocol to communicate with a registry, unless the
169 
+registry is allowed to be accessed over an insecure connection. Refer to the
170 
+[insecure registries](daemon.md#insecure-registries) section for more information.
171 
+
172 
+
173 
+## Pull a repository with multiple images
174 
+
175 
+By default, `docker pull` pulls a *single* image from the registry. A repository
176 
+can contain multiple images. To pull all images from a repository, provide the
177 
+`-a` (or `--all-tags`) option when using `docker pull`.
178 
+
179 
+This command pulls all images from the `fedora` repository:
180 
+
181 
+```bash
182 
+$ docker pull --all-tags fedora
183 
+
184 
+Pulling repository fedora
185 
+ad57ef8d78d7: Download complete
186 
+105182bb5e8b: Download complete
187 
+511136ea3c5a: Download complete
188 
+73bd853d2ea5: Download complete
189 
+....
190 
+
191 
+Status: Downloaded newer image for fedora
192 
+```
193 
+
194 
+After the pull has completed use the `docker images` command to see the
195 
+images that were pulled. The example below shows all the `fedora` images
196 
+that are present locally:
197 
+
198 
+```bash
199 
+$ docker images fedora
200 
+
201 
+REPOSITORY   TAG         IMAGE ID        CREATED      SIZE
202 
+fedora       rawhide     ad57ef8d78d7    5 days ago   359.3 MB
203 
+fedora       20          105182bb5e8b    5 days ago   372.7 MB
204 
+fedora       heisenbug   105182bb5e8b    5 days ago   372.7 MB
205 
+fedora       latest      105182bb5e8b    5 days ago   372.7 MB
206 
+```
207 
+
208 
+## Canceling a pull
52 209
53 210 
 Killing the `docker pull` process, for example by pressing `CTRL-c` while it is
54 211 
 running in a terminal, will terminate the pull operation.
212 
+
213 
+```bash
214 
+$ docker pull fedora
215 
+
216 
+Using default tag: latest
217 
+latest: Pulling from library/fedora
218 
+a3ed95caeb02: Pulling fs layer
219 
+236608c7b546: Pulling fs layer
220 
+^C
221 
+```
222 
+
223 
+> **Note**: Technically, the Engine terminates a pull operation when the
224 
+> connection between the Docker Engine daemon and the Docker Engine client
225 
+> initiating the pull is lost. If the connection with the Engine daemon is
226 
+> lost for other reasons than a manual interaction, the pull is also aborted.
man/docker-pull.1.md
History View file @ 32eff90
... ... 
@@ -16,7 +16,7 @@ This command pulls down an image or a repository from a registry. If
16 16 
 there is more than one image for a repository (e.g., fedora) then all
17 17 
 images for that repository name can be pulled down including any tags
18 18 
 (see the option **-a** or **--all-tags**).
19 
-
19 
+
20 20 
 If you do not specify a `REGISTRY_HOST`, the command uses Docker's public
21 21 
 registry located at `registry-1.docker.io` by default.
22 22
... ... 
@@ -27,58 +27,185 @@ registry located at `registry-1.docker.io` by default.
27 27 
 **--help**
28 28 
   Print usage statement
29 29
30 
-# EXAMPLE
30 
+# EXAMPLES
31 
+
32 
+### Pull an image from Docker Hub
33 
+
34 
+To download a particular image, or set of images (i.e., a repository), use
35 
+`docker pull`. If no tag is provided, Docker Engine uses the `:latest` tag as a
36 
+default. This command pulls the `debian:latest` image:
37 
+
38 
+    $ docker pull debian
39 
+
40 
+    Using default tag: latest
41 
+    latest: Pulling from library/debian
42 
+    fdd5d7827f33: Pull complete
43 
+    a3ed95caeb02: Pull complete
44 
+    Digest: sha256:e7d38b3517548a1c71e41bffe9c8ae6d6d29546ce46bf62159837aad072c90aa
45 
+    Status: Downloaded newer image for debian:latest
46 
+
47 
+Docker images can consist of multiple layers. In the example above, the image
48 
+consists of two layers; `fdd5d7827f33` and `a3ed95caeb02`.
49 
+
50 
+Layers can be reused by images. For example, the `debian:jessie` image shares
51 
+both layers with `debian:latest`. Pulling the `debian:jessie` image therefore
52 
+only pulls its metadata, but not its layers, because all layers are already
53 
+present locally:
54 
+
55 
+    $ docker pull debian:jessie
56 
+
57 
+    jessie: Pulling from library/debian
58 
+    fdd5d7827f33: Already exists
59 
+    a3ed95caeb02: Already exists
60 
+    Digest: sha256:a9c958be96d7d40df920e7041608f2f017af81800ca5ad23e327bc402626b58e
61 
+    Status: Downloaded newer image for debian:jessie
62 
+
63 
+To see which images are present locally, use the **docker-images(1)**
64 
+command:
65 
+
66 
+    $ docker images
67 
+
68 
+    REPOSITORY   TAG      IMAGE ID        CREATED      SIZE
69 
+    debian       jessie   f50f9524513f    5 days ago   125.1 MB
70 
+    debian       latest   f50f9524513f    5 days ago   125.1 MB
71 
+
72 
+Docker uses a content-addressable image store, and the image ID is a SHA256
73 
+digest covering the image's configuration and layers. In the example above,
74 
+`debian:jessie` and `debian:latest` have the same image ID because they are
75 
+actually the *same* image tagged with different names. Because they are the
76 
+same image, their layers are stored only once and do not consume extra disk
77 
+space.
78 
+
79 
+For more information about images, layers, and the content-addressable store,
80 
+refer to [understand images, containers, and storage drivers](https://docs.docker.com/engine/userguide/storagedriver/imagesandcontainers/)
81 
+in the online documentation.
82 
+
83 
+
84 
+## Pull an image by digest (immutable identifier)
85 
+
86 
+So far, you've pulled images by their name (and "tag"). Using names and tags is
87 
+a convenient way to work with images. When using tags, you can `docker pull` an
88 
+image again to make sure you have the most up-to-date version of that image.
89 
+For example, `docker pull ubuntu:14.04` pulls the latest version of the Ubuntu
90 
+14.04 image.
91 
+
92 
+In some cases you don't want images to be updated to newer versions, but prefer
93 
+to use a fixed version of an image. Docker enables you to pull an image by its
94 
+*digest*. When pulling an image by digest, you specify *exactly* which version
95 
+of an image to pull. Doing so, allows you to "pin" an image to that version,
96 
+and guarantee that the image you're using is always the same.
97 
+
98 
+To know the digest of an image, pull the image first. Let's pull the latest
99 
+`ubuntu:14.04` image from Docker Hub:
100 
+
101 
+    $ docker pull ubuntu:14.04
102 
+
103 
+    14.04: Pulling from library/ubuntu
104 
+    5a132a7e7af1: Pull complete
105 
+    fd2731e4c50c: Pull complete
106 
+    28a2f68d1120: Pull complete
107 
+    a3ed95caeb02: Pull complete
108 
+    Digest: sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2
109 
+    Status: Downloaded newer image for ubuntu:14.04
110 
+
111 
+Docker prints the digest of the image after the pull has finished. In the example
112 
+above, the digest of the image is:
113 
+
114 
+    sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2
115 
+
116 
+Docker also prints the digest of an image when *pushing* to a registry. This
117 
+may be useful if you want to pin to a version of the image you just pushed.
118 
+
119 
+A digest takes the place of the tag when pulling an image, for example, to
120 
+pull the above image by digest, run the following command:
31 121
32 
-## Pull a repository with multiple images with the -a|--all-tags option set to true.
33 
-Note that if the  image is previously downloaded then the status would be
34 
-`Status: Image is up to date for fedora`.
122 
+    $ docker pull ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2
123 
+
124 
+    sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2: Pulling from library/ubuntu
125 
+    5a132a7e7af1: Already exists
126 
+    fd2731e4c50c: Already exists
127 
+    28a2f68d1120: Already exists
128 
+    a3ed95caeb02: Already exists
129 
+    Digest: sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2
130 
+    Status: Downloaded newer image for ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2
131 
+
132 
+Digest can also be used in the `FROM` of a Dockerfile, for example:
133 
+
134 
+    FROM ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2
135 
+    MAINTAINER some maintainer <maintainer@example.com>
136 
+
137 
+> **Note**: Using this feature "pins" an image to a specific version in time.
138 
+> Docker will therefore not pull updated versions of an image, which may include
139 
+> security updates. If you want to pull an updated image, you need to change the
140 
+> digest accordingly.
141 
+
142 
+## Pulling from a different registry
143 
+
144 
+By default, `docker pull` pulls images from Docker Hub. It is also possible to
145 
+manually specify the path of a registry to pull from. For example, if you have
146 
+set up a local registry, you can specify its path to pull from it. A registry
147 
+path is similar to a URL, but does not contain a protocol specifier (`https://`).
148 
+
149 
+The following command pulls the `testing/test-image` image from a local registry
150 
+listening on port 5000 (`myregistry.local:5000`):
151 
+
152 
+    $ docker pull myregistry.local:5000/testing/test-image
153 
+
154 
+Docker uses the `https://` protocol to communicate with a registry, unless the
155 
+registry is allowed to be accessed over an insecure connection. Refer to the
156 
+[insecure registries](https://docs.docker.com/engine/reference/commandline/daemon/#insecure-registries)
157 
+section in the online documentation for more information.
158 
+
159 
+
160 
+## Pull a repository with multiple images
161 
+
162 
+By default, `docker pull` pulls a *single* image from the registry. A repository
163 
+can contain multiple images. To pull all images from a repository, provide the
164 
+`-a` (or `--all-tags`) option when using `docker pull`.
165 
+
166 
+This command pulls all images from the `fedora` repository:
35 167
36 168 
     $ docker pull --all-tags fedora
169 
+
37 170 
     Pulling repository fedora
38 171 
     ad57ef8d78d7: Download complete
39 172 
     105182bb5e8b: Download complete
40 173 
     511136ea3c5a: Download complete
41 174 
     73bd853d2ea5: Download complete
175 
+    ....
42 176
43 177 
     Status: Downloaded newer image for fedora
44 178
45 
-    $ docker images
179 
+After the pull has completed use the `docker images` command to see the
180 
+images that were pulled. The example below shows all the `fedora` images
181 
+that are present locally:
182 
+
183 
+    $ docker images fedora
184 
+
46 185 
     REPOSITORY   TAG         IMAGE ID        CREATED      SIZE
47 186 
     fedora       rawhide     ad57ef8d78d7    5 days ago   359.3 MB
48 187 
     fedora       20          105182bb5e8b    5 days ago   372.7 MB
49 188 
     fedora       heisenbug   105182bb5e8b    5 days ago   372.7 MB
50 189 
     fedora       latest      105182bb5e8b    5 days ago   372.7 MB
51 190
52 
-## Pull a repository with the -a|--all-tags option set to false (this is the default).
53 
-
54 
-    $ docker pull debian
55 
-    Using default tag: latest
56 
-    latest: Pulling from library/debian
57 
-    2c49f83e0b13: Pull complete
58 
-    4a5e6db8c069: Pull complete
59 
-
60 
-    Status: Downloaded newer image for debian:latest
61 
-
62 
-    $ docker images
63 
-    REPOSITORY   TAG         IMAGE ID        CREATED      SIZE
64 
-    debian       latest     4a5e6db8c069     5 days ago   125.1 MB
65 
-
66 191
67 
-## Pull an image, manually specifying path to Docker's public registry and tag
68 
-Note that if the  image is previously downloaded then the status would be
69 
-`Status: Image is up to date for registry.hub.docker.com/fedora:20`
192 
+## Canceling a pull
70 193
71 
-    $ docker pull registry.hub.docker.com/fedora:20
72 
-    Pulling repository fedora
73 
-    3f2fed40e4b0: Download complete
74 
-    511136ea3c5a: Download complete
75 
-    fd241224e9cf: Download complete
194 
+Killing the `docker pull` process, for example by pressing `CTRL-c` while it is
195 
+running in a terminal, will terminate the pull operation.
76 196
77 
-    Status: Downloaded newer image for registry.hub.docker.com/fedora:20
197 
+    $ docker pull fedora
78 198
79 
-    $ docker images
80 
-    REPOSITORY   TAG         IMAGE ID        CREATED      SIZE
81 
-    fedora       20          3f2fed40e4b0    4 days ago   372.7 MB
199 
+    Using default tag: latest
200 
+    latest: Pulling from library/fedora
201 
+    a3ed95caeb02: Pulling fs layer
202 
+    236608c7b546: Pulling fs layer
203 
+    ^C
204 
+
205 
+> **Note**: Technically, the Engine terminates a pull operation when the
206 
+> connection between the Docker Engine daemon and the Docker Engine client
207 
+> initiating the pull is lost. If the connection with the Engine daemon is
208 
+> lost for other reasons than a manual interaction, the pull is also aborted.
82 209
83 210
84 211 
 # HISTORY