github.com/kim0/docker@v0.6.2-0.20161130212042-4addda3f07e7/docs/reference/commandline/pull.md (about) 1 --- 2 title: "pull" 3 description: "The pull command description and usage" 4 keywords: ["pull, image, hub, docker"] 5 --- 6 7 <!-- This file is maintained within the docker/docker Github 8 repository at https://github.com/docker/docker/. Make all 9 pull requests against that repo. If you see this file in 10 another repository, consider it read-only there, as it will 11 periodically be overwritten by the definitive file. Pull 12 requests which include edits to this file in other repositories 13 will be rejected. 14 --> 15 16 # pull 17 18 ```markdown 19 Usage: docker pull [OPTIONS] NAME[:TAG|@DIGEST] 20 21 Pull an image or a repository from a registry 22 23 Options: 24 -a, --all-tags Download all tagged images in the repository 25 --disable-content-trust Skip image verification (default true) 26 --help Print usage 27 ``` 28 29 Most of your images will be created on top of a base image from the 30 [Docker Hub](https://hub.docker.com) registry. 31 32 [Docker Hub](https://hub.docker.com) contains many pre-built images that you 33 can `pull` and try without needing to define and configure your own. 34 35 To download a particular image, or set of images (i.e., a repository), 36 use `docker pull`. 37 38 ## Proxy configuration 39 40 If you are behind an HTTP proxy server, for example in corporate settings, 41 before open a connect to registry, you may need to configure the Docker 42 daemon's proxy settings, using the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` 43 environment variables. To set these environment variables on a host using 44 `systemd`, refer to the [control and configure Docker with systemd](https://docs.docker.com/engine/admin/systemd/#http-proxy) 45 for variables configuration. 46 47 ## Examples 48 49 ### Pull an image from Docker Hub 50 51 To download a particular image, or set of images (i.e., a repository), use 52 `docker pull`. If no tag is provided, Docker Engine uses the `:latest` tag as a 53 default. This command pulls the `debian:latest` image: 54 55 ```bash 56 $ docker pull debian 57 58 Using default tag: latest 59 latest: Pulling from library/debian 60 fdd5d7827f33: Pull complete 61 a3ed95caeb02: Pull complete 62 Digest: sha256:e7d38b3517548a1c71e41bffe9c8ae6d6d29546ce46bf62159837aad072c90aa 63 Status: Downloaded newer image for debian:latest 64 ``` 65 66 Docker images can consist of multiple layers. In the example above, the image 67 consists of two layers; `fdd5d7827f33` and `a3ed95caeb02`. 68 69 Layers can be reused by images. For example, the `debian:jessie` image shares 70 both layers with `debian:latest`. Pulling the `debian:jessie` image therefore 71 only pulls its metadata, but not its layers, because all layers are already 72 present locally: 73 74 ```bash 75 $ docker pull debian:jessie 76 77 jessie: Pulling from library/debian 78 fdd5d7827f33: Already exists 79 a3ed95caeb02: Already exists 80 Digest: sha256:a9c958be96d7d40df920e7041608f2f017af81800ca5ad23e327bc402626b58e 81 Status: Downloaded newer image for debian:jessie 82 ``` 83 84 To see which images are present locally, use the [`docker images`](images.md) 85 command: 86 87 ```bash 88 $ docker images 89 90 REPOSITORY TAG IMAGE ID CREATED SIZE 91 debian jessie f50f9524513f 5 days ago 125.1 MB 92 debian latest f50f9524513f 5 days ago 125.1 MB 93 ``` 94 95 Docker uses a content-addressable image store, and the image ID is a SHA256 96 digest covering the image's configuration and layers. In the example above, 97 `debian:jessie` and `debian:latest` have the same image ID because they are 98 actually the *same* image tagged with different names. Because they are the 99 same image, their layers are stored only once and do not consume extra disk 100 space. 101 102 For more information about images, layers, and the content-addressable store, 103 refer to [understand images, containers, and storage drivers](https://docs.docker.com/engine/userguide/storagedriver/imagesandcontainers/). 104 105 106 ## Pull an image by digest (immutable identifier) 107 108 So far, you've pulled images by their name (and "tag"). Using names and tags is 109 a convenient way to work with images. When using tags, you can `docker pull` an 110 image again to make sure you have the most up-to-date version of that image. 111 For example, `docker pull ubuntu:14.04` pulls the latest version of the Ubuntu 112 14.04 image. 113 114 In some cases you don't want images to be updated to newer versions, but prefer 115 to use a fixed version of an image. Docker enables you to pull an image by its 116 *digest*. When pulling an image by digest, you specify *exactly* which version 117 of an image to pull. Doing so, allows you to "pin" an image to that version, 118 and guarantee that the image you're using is always the same. 119 120 To know the digest of an image, pull the image first. Let's pull the latest 121 `ubuntu:14.04` image from Docker Hub: 122 123 ```bash 124 $ docker pull ubuntu:14.04 125 126 14.04: Pulling from library/ubuntu 127 5a132a7e7af1: Pull complete 128 fd2731e4c50c: Pull complete 129 28a2f68d1120: Pull complete 130 a3ed95caeb02: Pull complete 131 Digest: sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 132 Status: Downloaded newer image for ubuntu:14.04 133 ``` 134 135 Docker prints the digest of the image after the pull has finished. In the example 136 above, the digest of the image is: 137 138 sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 139 140 Docker also prints the digest of an image when *pushing* to a registry. This 141 may be useful if you want to pin to a version of the image you just pushed. 142 143 A digest takes the place of the tag when pulling an image, for example, to 144 pull the above image by digest, run the following command: 145 146 ```bash 147 $ docker pull ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 148 149 sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2: Pulling from library/ubuntu 150 5a132a7e7af1: Already exists 151 fd2731e4c50c: Already exists 152 28a2f68d1120: Already exists 153 a3ed95caeb02: Already exists 154 Digest: sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 155 Status: Downloaded newer image for ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 156 ``` 157 158 Digest can also be used in the `FROM` of a Dockerfile, for example: 159 160 ```Dockerfile 161 FROM ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 162 MAINTAINER some maintainer <maintainer@example.com> 163 ``` 164 165 > **Note**: Using this feature "pins" an image to a specific version in time. 166 > Docker will therefore not pull updated versions of an image, which may include 167 > security updates. If you want to pull an updated image, you need to change the 168 > digest accordingly. 169 170 171 ## Pulling from a different registry 172 173 By default, `docker pull` pulls images from [Docker Hub](https://hub.docker.com). It is also possible to 174 manually specify the path of a registry to pull from. For example, if you have 175 set up a local registry, you can specify its path to pull from it. A registry 176 path is similar to a URL, but does not contain a protocol specifier (`https://`). 177 178 The following command pulls the `testing/test-image` image from a local registry 179 listening on port 5000 (`myregistry.local:5000`): 180 181 ```bash 182 $ docker pull myregistry.local:5000/testing/test-image 183 ``` 184 185 Registry credentials are managed by [docker login](login.md). 186 187 Docker uses the `https://` protocol to communicate with a registry, unless the 188 registry is allowed to be accessed over an insecure connection. Refer to the 189 [insecure registries](dockerd.md#insecure-registries) section for more information. 190 191 192 ## Pull a repository with multiple images 193 194 By default, `docker pull` pulls a *single* image from the registry. A repository 195 can contain multiple images. To pull all images from a repository, provide the 196 `-a` (or `--all-tags`) option when using `docker pull`. 197 198 This command pulls all images from the `fedora` repository: 199 200 ```bash 201 $ docker pull --all-tags fedora 202 203 Pulling repository fedora 204 ad57ef8d78d7: Download complete 205 105182bb5e8b: Download complete 206 511136ea3c5a: Download complete 207 73bd853d2ea5: Download complete 208 .... 209 210 Status: Downloaded newer image for fedora 211 ``` 212 213 After the pull has completed use the `docker images` command to see the 214 images that were pulled. The example below shows all the `fedora` images 215 that are present locally: 216 217 ```bash 218 $ docker images fedora 219 220 REPOSITORY TAG IMAGE ID CREATED SIZE 221 fedora rawhide ad57ef8d78d7 5 days ago 359.3 MB 222 fedora 20 105182bb5e8b 5 days ago 372.7 MB 223 fedora heisenbug 105182bb5e8b 5 days ago 372.7 MB 224 fedora latest 105182bb5e8b 5 days ago 372.7 MB 225 ``` 226 227 ## Canceling a pull 228 229 Killing the `docker pull` process, for example by pressing `CTRL-c` while it is 230 running in a terminal, will terminate the pull operation. 231 232 ```bash 233 $ docker pull fedora 234 235 Using default tag: latest 236 latest: Pulling from library/fedora 237 a3ed95caeb02: Pulling fs layer 238 236608c7b546: Pulling fs layer 239 ^C 240 ``` 241 242 > **Note**: Technically, the Engine terminates a pull operation when the 243 > connection between the Docker Engine daemon and the Docker Engine client 244 > initiating the pull is lost. If the connection with the Engine daemon is 245 > lost for other reasons than a manual interaction, the pull is also aborted.