Updated July 1, 2023
Introduction to Docker Pull
The ‘docker pull’ is a Docker command to download a Docker image or a repository locally on the host from a public or private registry. When we run any container and the specified Docker image is not present locally, it first pulls it from the registry.In most cases, when creating custom Docker images, developers often download base images from the public registry, which is commonly ‘hub.docker.com’. These base images serve as the foundation for building and customizing their own Docker images. Different flags are available in this command; however, a few only works in the newer version.
Syntax:
docker pull [OPTIONS] NAME[:TAG|@DIGEST]
Options:
–all-tags, -a: It downloads all images with different tags in that repository.
–disable-content-trust: It will skip image verification before pulling it.
–platform: It is used to set the platform.
–quiet, -q: It pulls images silently (no verbose).
–help: It helps us to know more about the command if we forget.
docker pull --help
How Pull Command works in Docker?
When running the pull command from the command line, the process begins by checking locally or on the host for the presence of the specified Docker image. If the image does not exist locally, the Docker daemon proceeds to connect to the public registry, which is typical ‘hub.docker.com’, unless a private registry is specified in the ‘daemon.json’ file. The Docker daemon then initiates the process of pulling the Docker image mentioned in the command. It actually matches the digest of the image behind the scene. Also, if we don’t mention the tag, it pulls the image with the ‘latest’ tag by default.
If we are trying to access the registry behind the proxy server, we need to configure the Docker daemon’s proxy settings by setting environment variables on a host using systemd.
We can pull only 3 layers of an image simultaneously using this pull command by default, and if we have to download an image having more layers, then there might be a chance where it can throw a timeout issue if the internet connection is slow. We can adjust the ‘–max-concurrent-downloads’ option in the ‘daemon.json’ file.
Example
Let’s understand the command with a few examples.
Scenario: – Different ways to pull Docker images from Docker Hub.
1. Pull the ‘alpine’ image without any tag as shown below:
docker pull alpine
In the above example, we can see that if we don’t provide any tag, the Docker daemon pulls the image with the ‘latest’ tag by default and pulls the image only if an image exists with the latest tag.
2. Pull an image with a specific tag; for example, we will pull the same ‘alpine’ image with a different tag i.e. ‘edge’, as shown below: –
docker pull alpine:edge
In the above example, we can see that we have specified the tag after ‘:’ so we can specify any tag that you want to download; it might be a version like 3, 3.12, 3.12.0, etc. We can browse the public repository for available tags of any image.
3. We can even pull images by digest. We can see that there is a key called digest when we pull the images in the above examples, so we can use that digest to pull the image as shown below: –
docker pull alpine@sha256:3e92a8388546f6b15943678d323afdbbf1d950368264e0317b45e469dfa81d53
Pulling an image using the digest is particularly useful when the application relies on a specific version of a Docker image.
Let’s pull another image named ‘ubuntu’ using tag and digest as shown below: –
docker pull ubuntu:20.04
docker pull ubuntu@sha256:bc2f7250f69267c9c6b66d7b6a81a54d3878bb85f1ebb5f951c896d13e6ba537
In the above example, we have first used the tag to download the image and then used the digest of the same image to pull the image, and we can see the status that says ‘Image is up to date …..’ because we are pulling the same image.
Scenario
Scenario #1: Pull the Image from a Different Registry or Private Registry
- As we know, the pull command downloads images from the Docker hub by default. However, we can pull images from our private registry or any different registry; we just have to specify the path of that registry while pulling the image from that registry, for example, if we already have a registry running as a container on the same server, we can use below command to pull Docker images from that local registry.
docker pull localhost:5000/alpine
In the above snapshot, we can see that we have first mentioned the path of the registry followed by the repository name and then the tag and the path is nothing but the URL of that server without a protocol specifier (https://).
The important thing is the image must be available on the private registry. For the purpose of this example, first tagged an existing alpine image with the name ‘localhost:5000/alpine’ and pushed it to the local registry.
Scenario #2: Pull a Repository with all Available Tags
2. We can use the ‘–all-tags’ or ‘-a’ option to pull all images with different tags at once as the ‘docker pull’ command pulls only one image at a time by default, and the command is shown below: –
docker pull --all-tags alpine
In the above example, we can see that it has started downloading all the images with different tags from the ‘alpine’ repository. We can use the ‘ctrl+c’ keyboard shortcut to interrupt the pull. We can use the ‘docker image ls’ command to verify the same as shown in the below snapshot: –
docker image ls
Scenario #3: Pull the Docker Images which is not signed, and content-trust is enabled
We can use the ‘–disable-content-trust’ option to download unverified images as shown below: –
docker pull localhost:5000/alpine
docker pull --disable-content-trust localhost:5000/alpine
In the above snapshot, we can see that the first command throws an error while pulling the image as the image is not verified and the ‘DOCKER_CONTENT_TRUST’ is enabled; however, when we use the ‘—disable-content-trust’ option, we can pull the image without any error.
Scenario #4: Pull the Image without any verbose output
We can use the ‘–quiet’ or ‘-q’ option to suppress the verbose output as shown below: –
docker pull -q nginx:alpine
In the above snapshot, we can see that output does not show the different layers that are downloaded or digest or status as we can see those if we pull the image without ‘-q’ option as shown in the below snapshot: –
docker pull nginx:alpine
Advantages of Docker Pull
- It helps to download the images from any registry, whether might be a public registry or private registry.
- It can even pull the whole repository if required using the ‘–all-tags’ option.
- It helps to download unsigned Docker images; however, we should be aware of risks while doing so.
Conclusion
This is a handy and frequently used command while working with Docker. The ‘–platform’ option only works with experimental features enabled as of now. It is not recommended to download unsigned Docker images if you are not familiar with the image, like how it works or what it does.
Recommended Articles
This is a Guide to Docker Pull. Here we discuss the introduction, Scenario, and How Pull Command work in Docker with examples, respectively. You may also have a look at the following articles to learn more –
