Pull an image in Docker

Before you can run a Docker container, you must first pull down its image. This is the equivalent of downloading a package from a specific repository, and that's pretty much exactly what happens when you run the Docker pull command.

For example, let's say we wanted to pull down the Nginx image to run a local web server really quickly. We can do this by running:

docker image pull nginx

It’s such a common task to pull down images that the simpler docker pull alias is much more commonly used.

Docker image tags

When pulling down an image, we can also append a colon and then specify a tag after the image name.

You can think of tags sort of like labels. They represent the state of a Docker image at a specific point in time — kinda like a snapshot.

If you don’t specify a tag, Docker will use the latest tag by default. But we can also specify any other available tag, such as 1.29.

docker pull nginx:1.29

Which tag you use (and whether you decide to use a tag or not) depends on your needs, but I personally always use a specific tag, and rarely use latest. This is because a new image can be pushed to the registry that contains a major, sweeping update and break your builds. By targeting a specific label, you can better prevent this from happening.

Pull an image by digest

Sometimes you need even MORE predictability in your pulls. This is where pulling an image “by digest” comes into play.

Digests use an immutable identifier (a SHA256 hash) that locks an image to a specific version. This gives you a guarantee that you are always pulling the exact, same image every time a pull is executed.

After pulling down the Nginx 1.29 image, you will see a “Digest” property in the output:

1.29: Pulling from library/nginx
9a80f9a05524: Already exists 
baccdd222209: Pull complete 
26be9a3603ae: Pull complete 
8db204c3cb06: Pull complete 
ddc6b36d0e36: Pull complete 
d8ded761e35b: Pull complete 
8820d4aadbcd: Pull complete 
Digest: sha256:33e0bbc7ca9ecf108140af6288c7c9d1ecc77548cbfd3952fd8466a75edefe57
Status: Downloaded newer image for nginx:1.29
docker.io/library/nginx:1.29

The digest value starts with sha256: and is followed by a long list of random characters. This is a unique hash that is assigned just to this specific image build.

It is possible for a new Nginx 1.29 image to be pushed up to the registry which differs from the image that we just downloaded, even though it will still be tagged as 1.29. But by using a digest, we ensure that we will always pull down the exact image that we expect to get.

To use a digest instead of a tag, specify an @ sign (rather than :) followed by the digest value:

docker pull nginx@sha256:33e0bbc7ca9ecf108140af6288c7c9d1ecc77548cbfd3952fd8466a75edefe57

Docker image registries and official images

By default, all Docker images are downloaded from Docker Hub — Docker's official image registry — and have a corresponding URL which lists out all available tags. Visit http://hub.docker.com and search for the image name, for example: “nginx”.

Images can be classified as official images, which means that they have been pre-vetted by the Docker team, are typically great starting points for your own image builds, and are very widely used.

We can see that nginx is a “Docker Official Image” and has over 1 billion pulls. Looking at its details page, we can see all of the related tags, links to their related Dockerfiles, and documentation with info on how to run the image.