How to use docker image pull command to download images

Introduction

In this lab, you will learn how to use the docker pull command to download Docker images from registries. You will explore different methods for pulling images, including pulling a specific image by its tag from Docker Hub, pulling an image using its immutable digest for guaranteed version control, pulling all tagged images from a repository, and pulling images from registries other than Docker Hub.

By completing these steps, you will gain practical experience in acquiring Docker images, which is a fundamental skill for building and running containerized applications. You will learn how to specify image versions and sources, ensuring you can reliably obtain the images you need for your projects.

Skills Graph

Pull a specific image by tag from Docker Hub

In this step, you will learn how to pull a specific Docker image by its tag from Docker Hub. Docker Hub is a public registry that hosts many official and community-contributed Docker images. Pulling an image means downloading it from a registry to your local machine.

The basic command to pull an image is docker pull <image_name>:<tag>. If you don't specify a tag, Docker will pull the latest tag by default. However, it's a good practice to specify a tag to ensure you get a specific version of the image.

Let's pull the hello-world image with the latest tag. This is a very small image used to test if your Docker installation is working correctly.

docker pull hello-world:latest

You should see output indicating that Docker is downloading the image layers.

Using default tag: latest
latest: Pulling from library/hello-world
Digest: sha256:f52335ce493f8f15cfcf46725b2909db9087b688aedabbbd2a167ae30b6da6fc
Status: Downloaded newer image for hello-world:latest
docker.io/library/hello-world:latest

Now, let's pull the ubuntu image with a specific tag, for example, 20.04. This will download the Ubuntu 20.04 LTS image.

docker pull ubuntu:20.04

You will see similar output showing the download progress.

20.04: Pulling from library/ubuntu
... (download progress) ...
Status: Downloaded newer image for ubuntu:20.04
docker.io/library/ubuntu:20.04

To see the images you have pulled, you can use the docker images command.

docker images

This command lists all the images stored on your local machine, including their repository, tag, image ID, creation time, and size.

REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
ubuntu        20.04     ...            ...            ...
hello-world   latest    ...            ...            ...

You have successfully pulled specific images by tag from Docker Hub.

Pull an image by its immutable digest

In this step, you will learn how to pull a Docker image using its immutable digest. While tags are convenient, they can be updated to point to a different image version. A digest, on the other hand, is a unique identifier for a specific image layer configuration and its history. It's a more reliable way to ensure you are pulling the exact same image every time.

The format for pulling an image by digest is docker pull <image_name>@<digest>.

First, let's find the digest of an image we already have. We can use the docker images --digests command to show the digests of local images.

docker images --digests

You should see output similar to this, including the DIGEST column:

REPOSITORY    TAG       DIGEST                                                                      IMAGE ID       CREATED        SIZE
ubuntu        20.04     sha256:...   ...            ...
hello-world   latest    sha256:f52335ce493f8f15cfcf46725b2909db9087b688aedabbbd2a167ae30b6da6fc   ...            ...            ...

Let's use the digest of the hello-world image. Copy the full digest string (starting with sha256:).

Now, let's try pulling the hello-world image again, but this time using its digest. Replace <digest> with the actual digest you copied.

docker pull hello-world@sha256:f52335ce493f8f15cfcf46725b2909db9087b688aedabbbd2a167ae30b6da6fc

Since you likely already have this image layer, Docker will report that the image is up to date.

sha256:f52335ce493f8f15cfcf46725b2909db9087b688aedabbbd2a167ae30b6da6fc: Pulling from library/hello-world
Digest: sha256:f52335ce493f8f15cfcf46725b2909db9087b688aedabbbd2a167ae30b6da6fc
Status: Downloaded newer image for hello-world@sha256:f52335ce493f8f15cfcf46725b2909db9087b688aedabbbd2a167ae30b6da6fc
docker.io/library/hello-world@sha256:f52335ce493f8f15cfcf46725b2909db9087b688aedabbbd2a167ae30b6da6fc

Pulling by digest is particularly useful in production environments or automated scripts where you need to guarantee that you are deploying a specific, unchanging version of an image.

You can verify the images again using docker images --digests. You will see the hello-world image listed, potentially with both the tag and the digest if you pulled by tag previously.

docker images --digests

Pull all tagged images from a repository

In this step, you will learn how to pull all tagged images from a specific repository on Docker Hub. This can be useful when you want to download multiple versions of an image for testing or other purposes.

To pull all tagged images from a repository, you can use the docker pull -a <image_name> command. The -a flag stands for "all-tags".

Let's try pulling all tagged images for the alpine repository. Alpine is a lightweight Linux distribution often used in containers.

docker pull -a alpine

This command will initiate the download of all images in the alpine repository that have a tag. You will see output showing the download of various tags like latest, 3.14, 3.15, etc.

Using default tag: latest
latest: Pulling from library/alpine
... (download progress for various tags) ...
Status: Downloaded newer image for alpine:latest
Status: Downloaded newer image for alpine:3.14
Status: Downloaded newer image for alpine:3.15
...
docker.io/library/alpine:latest
docker.io/library/alpine:3.14
docker.io/library/alpine:3.15
...

Depending on the number of tags in the repository, this command might take some time to complete.

Once the command finishes, you can use docker images to see all the alpine images you have pulled.

docker images | grep alpine

You will see a list of alpine images with different tags.

REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
alpine        latest    ...            ...            ...
alpine        3.14      ...            ...            ...
alpine        3.15      ...            ...            ...
...

This method is efficient for downloading multiple versions of an image from a single repository.

Pull an image from a different registry

In this step, you will learn how to pull a Docker image from a registry other than Docker Hub. While Docker Hub is the default, you might need to pull images from private registries, cloud provider registries (like Google Container Registry, Amazon Elastic Container Registry), or other public registries.

To pull an image from a different registry, you need to specify the registry's hostname before the image name. The format is typically <registry_hostname>/<image_name>:<tag> or <registry_hostname>/<user_or_organization>/<image_name>:<tag>.

For this example, we will pull an image from Google Container Registry (GCR). We will pull the hello-app image from the google-samples project. The registry hostname for GCR is gcr.io.

docker pull gcr.io/google-samples/hello-app:1.0

This command tells Docker to pull the image named hello-app with the tag 1.0 from the registry located at gcr.io within the google-samples project.

You will see output indicating the download process from the specified registry.

1.0: Pulling from google-samples/hello-app
... (download progress) ...
Status: Downloaded newer image for gcr.io/google-samples/hello-app:1.0
gcr.io/google-samples/hello-app:1.0

After the pull is complete, you can list your local images using docker images to see the image you just pulled from GCR.

docker images

You should see gcr.io/google-samples/hello-app listed in your images.

REPOSITORY                         TAG       IMAGE ID       CREATED        SIZE
gcr.io/google-samples/hello-app    1.0       ...            ...            ...
ubuntu                             20.04     ...            ...            ...
hello-world                        latest    ...            ...            ...
alpine                             latest    ...            ...            ...
alpine                             3.14      ...            ...            ...
alpine                             3.15      ...            ...            ...
...

This demonstrates how to pull images from registries other than the default Docker Hub by specifying the registry hostname.

Summary

In this lab, you learned how to use the docker pull command to download Docker images from registries. You started by pulling specific images from Docker Hub using their tags, understanding that specifying a tag is crucial for getting a particular version. You also learned how to view the images you have downloaded locally using the docker images command.

The lab further demonstrated how to pull an image using its immutable digest, ensuring you retrieve the exact same image version regardless of tag changes. You also explored pulling all tagged images from a repository and pulling images from registries other than Docker Hub, expanding your ability to access images from various sources.