docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
docs/_data/engine-cli/docker_image_pull.yaml

108 lines
8.6 KiB
YAML
Raw Blame History

command: docker image pull
short: Pull an image or a repository from a registry
long: "This command pulls down an image or a repository from a registry. If\nthere
is more than one image for a repository (e.g., fedora) then all\nimages for that
repository name can be pulled down including any tags\n(see the option **-a** or
**--all-tags**).\n\nIf you do not specify a `REGISTRY_HOST`, the command uses Docker's
public\nregistry located at `registry-1.docker.io` by default. \n\n# EXAMPLES\n\n###
Pull an image from Docker Hub\n\nTo download a particular image, or set of images
(i.e., a repository), use\n`docker image pull`. If no tag is provided, Docker Engine
uses the `:latest` tag as a\ndefault. This command pulls the `debian:latest` image:\n\n
\ $ docker image pull debian\n\n Using default tag: latest\n latest: Pulling
from library/debian\n fdd5d7827f33: Pull complete\n a3ed95caeb02: Pull complete\n
\ Digest: sha256:e7d38b3517548a1c71e41bffe9c8ae6d6d29546ce46bf62159837aad072c90aa\n
\ Status: Downloaded newer image for debian:latest\n\nDocker images can consist
of multiple layers. In the example above, the image\nconsists of two layers; `fdd5d7827f33`
and `a3ed95caeb02`.\n\nLayers can be reused by images. For example, the `debian:jessie`
image shares\nboth layers with `debian:latest`. Pulling the `debian:jessie` image
therefore\nonly pulls its metadata, but not its layers, because all layers are already\npresent
locally:\n\n $ docker image pull debian:jessie\n\n jessie: Pulling from library/debian\n
\ fdd5d7827f33: Already exists\n a3ed95caeb02: Already exists\n Digest:
sha256:a9c958be96d7d40df920e7041608f2f017af81800ca5ad23e327bc402626b58e\n Status:
Downloaded newer image for debian:jessie\n\nTo see which images are present locally,
use the **docker-images(1)**\ncommand:\n\n $ docker images\n\n REPOSITORY
\ TAG IMAGE ID CREATED SIZE\n debian jessie f50f9524513f
\ 5 days ago 125.1 MB\n debian latest f50f9524513f 5 days ago
\ 125.1 MB\n\nDocker uses a content-addressable image store, and the image ID is
a SHA256\ndigest covering the image's configuration and layers. In the example above,\n`debian:jessie`
and `debian:latest` have the same image ID because they are\nactually the *same*
image tagged with different names. Because they are the\nsame image, their layers
are stored only once and do not consume extra disk\nspace.\n\nFor more information
about images, layers, and the content-addressable store,\nrefer to [understand images,
containers, and storage drivers](https://docs.docker.com/engine/userguide/storagedriver/imagesandcontainers/)\nin
the online documentation.\n\n\n## Pull an image by digest (immutable identifier)\n\nSo
far, you've pulled images by their name (and \"tag\"). Using names and tags is\na
convenient way to work with images. When using tags, you can `docker image pull`
an\nimage again to make sure you have the most up-to-date version of that image.\nFor
example, `docker image pull ubuntu:14.04` pulls the latest version of the Ubuntu\n14.04
image.\n\nIn some cases you don't want images to be updated to newer versions, but
prefer\nto use a fixed version of an image. Docker enables you to pull an image
by its\n*digest*. When pulling an image by digest, you specify *exactly* which version\nof
an image to pull. Doing so, allows you to \"pin\" an image to that version,\nand
guarantee that the image you're using is always the same.\n\nTo know the digest
of an image, pull the image first. Let's pull the latest\n`ubuntu:14.04` image from
Docker Hub:\n\n $ docker image pull ubuntu:14.04\n\n 14.04: Pulling from library/ubuntu\n
\ 5a132a7e7af1: Pull complete\n fd2731e4c50c: Pull complete\n 28a2f68d1120:
Pull complete\n a3ed95caeb02: Pull complete\n Digest: sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2\n
\ Status: Downloaded newer image for ubuntu:14.04\n\nDocker prints the digest
of the image after the pull has finished. In the example\nabove, the digest of the
image is:\n\n sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2\n\nDocker
also prints the digest of an image when *pushing* to a registry. This\nmay be useful
if you want to pin to a version of the image you just pushed.\n\nA digest takes
the place of the tag when pulling an image, for example, to \npull the above image
by digest, run the following command:\n\n $ docker image pull ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2\n\n
\ sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2: Pulling
from library/ubuntu\n 5a132a7e7af1: Already exists\n fd2731e4c50c: Already
exists\n 28a2f68d1120: Already exists\n a3ed95caeb02: Already exists\n Digest:
sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2\n Status:
Downloaded newer image for ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2\n\nDigest
can also be used in the `FROM` of a Dockerfile, for example:\n\n FROM ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2\n
\ MAINTAINER some maintainer <maintainer@example.com>\n\n> **Note**: Using this
feature \"pins\" an image to a specific version in time.\n> Docker will therefore
not pull updated versions of an image, which may include \n> security updates. If
you want to pull an updated image, you need to change the\n> digest accordingly.\n\n##
Pulling from a different registry\n\nBy default, `docker image pull` pulls images
from Docker Hub. It is also possible to\nmanually specify the path of a registry
to pull from. For example, if you have\nset up a local registry, you can specify
its path to pull from it. A registry\npath is similar to a URL, but does not contain
a protocol specifier (`https://`).\n\nThe following command pulls the `testing/test-image`
image from a local registry\nlistening on port 5000 (`myregistry.local:5000`):\n\n
\ $ docker image pull myregistry.local:5000/testing/test-image\n\nRegistry credentials
are managed by **docker-login(1)**.\n\nDocker uses the `https://` protocol to communicate
with a registry, unless the\nregistry is allowed to be accessed over an insecure
connection. Refer to the\n[insecure registries](https://docs.docker.com/engine/reference/commandline/daemon/#insecure-registries)\nsection
in the online documentation for more information.\n\n\n## Pull a repository with
multiple images\n\nBy default, `docker image pull` pulls a *single* image from the
registry. A repository\ncan contain multiple images. To pull all images from a repository,
provide the\n`-a` (or `--all-tags`) option when using `docker image pull`.\n\nThis
command pulls all images from the `fedora` repository:\n\n $ docker image pull
--all-tags fedora\n\n Pulling repository fedora\n ad57ef8d78d7: Download complete\n
\ 105182bb5e8b: Download complete\n 511136ea3c5a: Download complete\n 73bd853d2ea5:
Download complete\n ....\n\n Status: Downloaded newer image for fedora\n\nAfter
the pull has completed use the `docker images` command to see the\nimages that were
pulled. The example below shows all the `fedora` images\nthat are present locally:\n\n
\ $ docker images fedora\n\n REPOSITORY TAG IMAGE ID CREATED
\ SIZE\n fedora rawhide ad57ef8d78d7 5 days ago 359.3 MB\n
\ fedora 20 105182bb5e8b 5 days ago 372.7 MB\n fedora heisenbug
\ 105182bb5e8b 5 days ago 372.7 MB\n fedora latest 105182bb5e8b
\ 5 days ago 372.7 MB\n\n\n## Canceling a pull\n\nKilling the `docker image
pull` process, for example by pressing `CTRL-c` while it is\nrunning in a terminal,
will terminate the pull operation.\n\n $ docker image pull fedora\n\n Using
default tag: latest\n latest: Pulling from library/fedora\n a3ed95caeb02:
Pulling fs layer\n 236608c7b546: Pulling fs layer\n ^C\n\n> **Note**: Technically,
the Engine terminates a pull operation when the\n> connection between the Docker
Engine daemon and the Docker Engine client\n> initiating the pull is lost. If the
connection with the Engine daemon is\n> lost for other reasons than a manual interaction,
the pull is also aborted.\n"
usage: docker image pull [OPTIONS] NAME[:TAG|@DIGEST]
pname: docker image
plink: docker_image.yaml
options:
- option: all-tags
shorthand: a
default_value: "false"
description: Download all tagged images in the repository
- option: disable-content-trust
default_value: "true"
description: Skip image verification
Reference in New Issue View Git Blame Copy Permalink