How to use docker pull

When you're working with Docker, you'll often need to download images from a registry. The most common command for this is docker pull. Let's walk through how to use it and some of the options available.

First off, docker pull is actually a shorthand for docker image pull. Both commands do the same thing: they download images from a registry, which is usually Docker Hub. Docker Hub is like a big library of pre-built images that you can use as a starting point for your own containers.

Here's how you use it:

docker pull [OPTIONS] NAME[:TAG|@DIGEST]

Let's break this down:

• NAME is the name of the image you want to pull. For example, if you want to pull the latest version of the Debian image, you'd use debian.
• TAG is optional. If you don't specify a tag, Docker will use latest by default. So docker pull debian is the same as docker pull debian:latest.
• DIGEST is another optional way to specify the image. We'll talk more about this later.

Here's an example of pulling the latest Debian image:

docker pull debian

When you run this command, Docker will download the debian:latest image. If you look closely at the output, you'll see something like this:

e756f3fdd6a3: Pull complete
Digest: sha256:123456789abcdef
Status: Downloaded newer image for debian:latest

The long string e756f3fdd6a3 is the ID of a layer in the image. Docker images are made up of layers, and each layer has a unique ID. In this case, the debian:latest image only has one layer.

Now, let's say you want to pull a different version of Debian, like debian:bookworm. If you've already pulled debian:latest and it shares the same layer as debian:bookworm, Docker won't need to download the layer again. It will just pull the metadata for debian:bookworm:

docker pull debian:bookworm

You can check which images you have locally with the docker images command:

docker images

This will show you a list of all the images on your system, including their tags and IDs.

Now, let's talk about some of the options you can use with docker pull:

• -a or --all-tags: This option tells Docker to pull all the tagged versions of an image from a repository. For example, if you want to pull all versions of the Ubuntu image, you'd use:

  docker pull -a ubuntu
  

  
  After the pull is complete, you can use docker images to see all the Ubuntu images you now have locally.
• --disable-content-trust: By default, Docker verifies the integrity of the images it pulls. If you want to skip this verification, you can use this option. It's set to true by default, so you only need to use it if you want to turn it off.
• --platform: If you're using a registry that supports multiple platforms, you can specify which platform you want to pull an image for. This is useful if you're working with different architectures.
• -q or --quiet: This option makes the pull command less chatty. It suppresses the verbose output, so you just see the essential information.

If you're behind a proxy server, you might need to configure Docker's proxy settings before you can pull images. You can do this by editing the Docker daemon's configuration.

By default, Docker will pull three layers of an image at a time. If you're on a slow connection, you might want to lower this number to avoid timeout issues. You can do this with the --max-concurrent-downloads option when you start the Docker daemon.

Sometimes, you might want to pull an image by its digest instead of its tag. A digest is a unique identifier for a specific version of an image. When you pull an image by its digest, you're guaranteed to get the exact same version every time. This is useful if you want to "pin" your application to a specific version of an image.

To pull an image by its digest, you first need to know the digest. You can find this out by pulling the image with a tag first. For example:

docker pull ubuntu:24.04

The output will include the digest:

Digest: sha256:abcdef123456789

Now you can pull the image by its digest:

docker pull ubuntu@sha256:abcdef123456789

You can also use a digest in a Dockerfile:

FROM ubuntu@sha256:abcdef123456789

Just keep in mind that if you use a digest, you won't get automatic updates to the image. If you want to update to a new version, you'll need to change the digest.

By default, docker pull pulls images from Docker Hub. But you can also pull from other registries. To do this, you just need to specify the registry path in the pull command. For example, if you have a local registry running on myregistry.local:5000, you can pull from it like this:

docker pull myregistry.local:5000/testing/test-image

If you need to authenticate with the registry, you can use the docker login command first.

Finally, if you need to cancel a pull operation, you can just press CTRL-c in the terminal where the pull is running. Docker will terminate the pull and clean up any partially downloaded data.

That's the basics of using docker pull! It's a simple but powerful command that lets you easily download images from registries and start building your Docker-based applications.