github.com/45cali/docker@v1.11.1/docs/reference/commandline/pull.md (about) 1 <!--[metadata]> 2 +++ 3 title = "pull" 4 description = "The pull command description and usage" 5 keywords = ["pull, image, hub, docker"] 6 [menu.main] 7 parent = "smn_cli" 8 +++ 9 <![end-metadata]--> 10 11 # pull 12 13 Usage: docker pull [OPTIONS] NAME[:TAG] | [REGISTRY_HOST[:REGISTRY_PORT]/]NAME[:TAG] 14 15 Pull an image or a repository from the registry 16 17 -a, --all-tags Download all tagged images in the repository 18 --disable-content-trust=true Skip image verification 19 --help Print usage 20 21 Most of your images will be created on top of a base image from the 22 [Docker Hub](https://hub.docker.com) registry. 23 24 [Docker Hub](https://hub.docker.com) contains many pre-built images that you 25 can `pull` and try without needing to define and configure your own. 26 27 To download a particular image, or set of images (i.e., a repository), 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 Registry credentials are managed by [docker login](login.md). 169 170 Docker uses the `https://` protocol to communicate with a registry, unless the 171 registry is allowed to be accessed over an insecure connection. Refer to the 172 [insecure registries](daemon.md#insecure-registries) section for more information. 173 174 175 ## Pull a repository with multiple images 176 177 By default, `docker pull` pulls a *single* image from the registry. A repository 178 can contain multiple images. To pull all images from a repository, provide the 179 `-a` (or `--all-tags`) option when using `docker pull`. 180 181 This command pulls all images from the `fedora` repository: 182 183 ```bash 184 $ docker pull --all-tags fedora 185 186 Pulling repository fedora 187 ad57ef8d78d7: Download complete 188 105182bb5e8b: Download complete 189 511136ea3c5a: Download complete 190 73bd853d2ea5: Download complete 191 .... 192 193 Status: Downloaded newer image for fedora 194 ``` 195 196 After the pull has completed use the `docker images` command to see the 197 images that were pulled. The example below shows all the `fedora` images 198 that are present locally: 199 200 ```bash 201 $ docker images fedora 202 203 REPOSITORY TAG IMAGE ID CREATED SIZE 204 fedora rawhide ad57ef8d78d7 5 days ago 359.3 MB 205 fedora 20 105182bb5e8b 5 days ago 372.7 MB 206 fedora heisenbug 105182bb5e8b 5 days ago 372.7 MB 207 fedora latest 105182bb5e8b 5 days ago 372.7 MB 208 ``` 209 210 ## Canceling a pull 211 212 Killing the `docker pull` process, for example by pressing `CTRL-c` while it is 213 running in a terminal, will terminate the pull operation. 214 215 ```bash 216 $ docker pull fedora 217 218 Using default tag: latest 219 latest: Pulling from library/fedora 220 a3ed95caeb02: Pulling fs layer 221 236608c7b546: Pulling fs layer 222 ^C 223 ``` 224 225 > **Note**: Technically, the Engine terminates a pull operation when the 226 > connection between the Docker Engine daemon and the Docker Engine client 227 > initiating the pull is lost. If the connection with the Engine daemon is 228 > lost for other reasons than a manual interaction, the pull is also aborted.