Table of Contents
Getting Ready to Pull Images
Docker Hub is the default public registry that Docker uses to find and download images. When you run most image related commands without specifying a registry, Docker talks to Docker Hub automatically.
Before you pull images, make sure Docker is installed and the daemon is running. You do not need a Docker Hub account to pull public images, but you do need one for private images or higher rate limits.
The Basic `docker pull` Command
To download an image from Docker Hub, you use the docker pull command followed by the image name. At its simplest it looks like this:
docker pull ubuntu
This tells Docker to contact Docker Hub, find the ubuntu image, download its layers, and store it locally. When the command completes, the image becomes available to create containers.
Key rule: If you do not specify a tag, Docker automatically uses the latest tag, so docker pull ubuntu and docker pull ubuntu:latest are equivalent.
Image Names and Tags
An image name usually has two parts, the repository name and an optional tag, separated by a colon. For example:
nginx:1.25
Here, nginx is the repository name and 1.25 is the tag that points to a specific version. If you omit the tag, Docker uses latest, which is just another tag, not a guarantee of the newest or safest version.
You can pull different versions of the same image by changing the tag. For instance, you might pull a long term support version of Ubuntu with:
docker pull ubuntu:20.04
This allows you to control exactly which version you use, which is important for reproducibility and stability.
Important: Always prefer explicit tags, such as ubuntu:22.04 or nginx:1.25, instead of relying on :latest in long lived projects.
Official Images and User Images
On Docker Hub you will encounter official images and images published by individual users or organizations.
When you pull an image with a simple name like ubuntu or nginx without a slash, you are usually pulling an official image that is curated and maintained under a special program on Docker Hub.
User or organization images typically include a namespace, for example:
someuser/myapp:1.0
In this case, someuser is the Docker Hub username or organization name, and myapp is the repository under that account. Docker will search Docker Hub in that namespace for the image.
If you want to be very explicit, you can include the full registry address, although for Docker Hub this is usually optional. For instance:
docker pull docker.io/library/nginx:latest
is equivalent to docker pull nginx because docker.io and library are the default registry and namespace for official images.
Pulling Specific Architecture or Variant
Some images on Docker Hub are multi architecture and support different CPU types such as amd64 or arm64. By default, Docker selects the variant that matches your system. In some situations, such as building images for different platforms, you may need to control the platform explicitly.
You can do this with the --platform option:
docker pull --platform=linux/amd64 nginx:latest
This is useful on Apple silicon machines if you need the image variant that behaves like a traditional x86 64 environment.
Understanding What Happens During a Pull
When you run docker pull, Docker performs several steps in the background. It resolves the image name and tag on Docker Hub, identifies the content that matches that reference, then downloads the image layers that you do not already have locally. If some layers are already present from another image, Docker reuses them and skips downloading them again.
You will typically see output that shows each layer being pulled or marked as already present, followed by the final digest and status message that the download is complete.
Important statement: Pulling an image may reuse existing layers from other images, so downloading one image can make future pulls faster and smaller.
Pulling Private Images
Private repositories on Docker Hub require authentication before you can pull their images. To access them, you log in with your Docker Hub credentials:
docker login
After a successful login, Docker stores authentication information on your machine and uses it to authorize subsequent pulls.
To pull a private image after logging in you use docker pull in the same way as for public images, for example:
docker pull mycompany/private-app:2.0
If your login does not have permission to access that image, the pull will fail with an authorization error.
Updating an Existing Image
If you already have an image locally and you run docker pull for the same name and tag, Docker checks Docker Hub for a newer version. If a new version exists for that tag, Docker downloads the new layers and updates the local copy.
For example, if nginx:1.25 is updated upstream and you run:
docker pull nginx:1.25
your local image is refreshed to match the updated content. If there is no change in the registry for that tag, Docker reports that the image is up to date.
Verifying Pulled Images
After pulling images from Docker Hub, you can confirm that they are available locally using image listing commands that are covered in the next chapters. It is often helpful to verify that the correct tag and version are present, especially when you work with multiple variants of the same base image.
At this stage, the important skill is to connect the image name and tag you intend to use in your containers with what you have just pulled from Docker Hub.