github.com/olljanat/moby@v1.13.1/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 ## Concurrent downloads 48 49 By default the Docker daemon will pull three layers of an image at a time. 50 If you are on a low bandwidth connection this may cause timeout issues and you may want to lower 51 this via the `--max-concurrent-downloads` daemon option. See the 52 [daemon documentation](dockerd.md) for more details. 53 54 ## Examples 55 56 ### Pull an image from Docker Hub 57 58 To download a particular image, or set of images (i.e., a repository), use 59 `docker pull`. If no tag is provided, Docker Engine uses the `:latest` tag as a 60 default. This command pulls the `debian:latest` image: 61 62 ```bash 63 $ docker pull debian 64 65 Using default tag: latest 66 latest: Pulling from library/debian 67 fdd5d7827f33: Pull complete 68 a3ed95caeb02: Pull complete 69 Digest: sha256:e7d38b3517548a1c71e41bffe9c8ae6d6d29546ce46bf62159837aad072c90aa 70 Status: Downloaded newer image for debian:latest 71 ``` 72 73 Docker images can consist of multiple layers. In the example above, the image 74 consists of two layers; `fdd5d7827f33` and `a3ed95caeb02`. 75 76 Layers can be reused by images. For example, the `debian:jessie` image shares 77 both layers with `debian:latest`. Pulling the `debian:jessie` image therefore 78 only pulls its metadata, but not its layers, because all layers are already 79 present locally: 80 81 ```bash 82 $ docker pull debian:jessie 83 84 jessie: Pulling from library/debian 85 fdd5d7827f33: Already exists 86 a3ed95caeb02: Already exists 87 Digest: sha256:a9c958be96d7d40df920e7041608f2f017af81800ca5ad23e327bc402626b58e 88 Status: Downloaded newer image for debian:jessie 89 ``` 90 91 To see which images are present locally, use the [`docker images`](images.md) 92 command: 93 94 ```bash 95 $ docker images 96 97 REPOSITORY TAG IMAGE ID CREATED SIZE 98 debian jessie f50f9524513f 5 days ago 125.1 MB 99 debian latest f50f9524513f 5 days ago 125.1 MB 100 ``` 101 102 Docker uses a content-addressable image store, and the image ID is a SHA256 103 digest covering the image's configuration and layers. In the example above, 104 `debian:jessie` and `debian:latest` have the same image ID because they are 105 actually the *same* image tagged with different names. Because they are the 106 same image, their layers are stored only once and do not consume extra disk 107 space. 108 109 For more information about images, layers, and the content-addressable store, 110 refer to [understand images, containers, and storage drivers](https://docs.docker.com/engine/userguide/storagedriver/imagesandcontainers/). 111 112 113 ## Pull an image by digest (immutable identifier) 114 115 So far, you've pulled images by their name (and "tag"). Using names and tags is 116 a convenient way to work with images. When using tags, you can `docker pull` an 117 image again to make sure you have the most up-to-date version of that image. 118 For example, `docker pull ubuntu:14.04` pulls the latest version of the Ubuntu 119 14.04 image. 120 121 In some cases you don't want images to be updated to newer versions, but prefer 122 to use a fixed version of an image. Docker enables you to pull an image by its 123 *digest*. When pulling an image by digest, you specify *exactly* which version 124 of an image to pull. Doing so, allows you to "pin" an image to that version, 125 and guarantee that the image you're using is always the same. 126 127 To know the digest of an image, pull the image first. Let's pull the latest 128 `ubuntu:14.04` image from Docker Hub: 129 130 ```bash 131 $ docker pull ubuntu:14.04 132 133 14.04: Pulling from library/ubuntu 134 5a132a7e7af1: Pull complete 135 fd2731e4c50c: Pull complete 136 28a2f68d1120: Pull complete 137 a3ed95caeb02: Pull complete 138 Digest: sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 139 Status: Downloaded newer image for ubuntu:14.04 140 ``` 141 142 Docker prints the digest of the image after the pull has finished. In the example 143 above, the digest of the image is: 144 145 sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 146 147 Docker also prints the digest of an image when *pushing* to a registry. This 148 may be useful if you want to pin to a version of the image you just pushed. 149 150 A digest takes the place of the tag when pulling an image, for example, to 151 pull the above image by digest, run the following command: 152 153 ```bash 154 $ docker pull ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 155 156 sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2: Pulling from library/ubuntu 157 5a132a7e7af1: Already exists 158 fd2731e4c50c: Already exists 159 28a2f68d1120: Already exists 160 a3ed95caeb02: Already exists 161 Digest: sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 162 Status: Downloaded newer image for ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 163 ``` 164 165 Digest can also be used in the `FROM` of a Dockerfile, for example: 166 167 ```Dockerfile 168 FROM ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 169 MAINTAINER some maintainer <maintainer@example.com> 170 ``` 171 172 > **Note**: Using this feature "pins" an image to a specific version in time. 173 > Docker will therefore not pull updated versions of an image, which may include 174 > security updates. If you want to pull an updated image, you need to change the 175 > digest accordingly. 176 177 178 ## Pulling from a different registry 179 180 By default, `docker pull` pulls images from [Docker Hub](https://hub.docker.com). It is also possible to 181 manually specify the path of a registry to pull from. For example, if you have 182 set up a local registry, you can specify its path to pull from it. A registry 183 path is similar to a URL, but does not contain a protocol specifier (`https://`). 184 185 The following command pulls the `testing/test-image` image from a local registry 186 listening on port 5000 (`myregistry.local:5000`): 187 188 ```bash 189 $ docker pull myregistry.local:5000/testing/test-image 190 ``` 191 192 Registry credentials are managed by [docker login](login.md). 193 194 Docker uses the `https://` protocol to communicate with a registry, unless the 195 registry is allowed to be accessed over an insecure connection. Refer to the 196 [insecure registries](dockerd.md#insecure-registries) section for more information. 197 198 199 ## Pull a repository with multiple images 200 201 By default, `docker pull` pulls a *single* image from the registry. A repository 202 can contain multiple images. To pull all images from a repository, provide the 203 `-a` (or `--all-tags`) option when using `docker pull`. 204 205 This command pulls all images from the `fedora` repository: 206 207 ```bash 208 $ docker pull --all-tags fedora 209 210 Pulling repository fedora 211 ad57ef8d78d7: Download complete 212 105182bb5e8b: Download complete 213 511136ea3c5a: Download complete 214 73bd853d2ea5: Download complete 215 .... 216 217 Status: Downloaded newer image for fedora 218 ``` 219 220 After the pull has completed use the `docker images` command to see the 221 images that were pulled. The example below shows all the `fedora` images 222 that are present locally: 223 224 ```bash 225 $ docker images fedora 226 227 REPOSITORY TAG IMAGE ID CREATED SIZE 228 fedora rawhide ad57ef8d78d7 5 days ago 359.3 MB 229 fedora 20 105182bb5e8b 5 days ago 372.7 MB 230 fedora heisenbug 105182bb5e8b 5 days ago 372.7 MB 231 fedora latest 105182bb5e8b 5 days ago 372.7 MB 232 ``` 233 234 ## Canceling a pull 235 236 Killing the `docker pull` process, for example by pressing `CTRL-c` while it is 237 running in a terminal, will terminate the pull operation. 238 239 ```bash 240 $ docker pull fedora 241 242 Using default tag: latest 243 latest: Pulling from library/fedora 244 a3ed95caeb02: Pulling fs layer 245 236608c7b546: Pulling fs layer 246 ^C 247 ``` 248 249 > **Note**: Technically, the Engine terminates a pull operation when the 250 > connection between the Docker Engine daemon and the Docker Engine client 251 > initiating the pull is lost. If the connection with the Engine daemon is 252 > lost for other reasons than a manual interaction, the pull is also aborted.