Search
English
Contents
  1. Docker tutorial
Getting started
  1. What is Docker
  2. Install Docker
  3. Docker Desktop interface tour
  4. Your first container
  5. Images
  6. Container lifecycle
  7. docker run flags
  8. View logs and debug
Images and Dockerfile
  1. Dockerfile basics
  2. Generate files with docker init
  3. Dockerfile instructions
  4. Build Cache and Optimization
  5. Multi-stage builds
  6. Push to Docker Hub
Data and networking
  1. Volumes and data persistence
  2. Networking and container communication
  3. Environment variables and .env
Docker Compose
  1. Docker Compose Tutorial
  2. compose.yaml syntax
  3. Docker Compose commands
  4. Build a WordPress Site
Real-world examples
  1. Python apps
  2. Node.js apps
  3. Nginx and reverse proxying
  4. MySQL
  5. PostgreSQL
  6. Redis
Operations and advanced topics
  1. Reclaim disk space
  2. Security best practices
  3. Rootless and Podman
  4. Multi-platform images
  5. Build automatically with GitHub Actions
  6. Deploy to a cloud server
  7. Internals
  8. Common error messages
  9. Docker command cheat sheet
Command reference
  1. docker build
  2. docker pull
  3. docker push
  4. docker rmi
  5. docker exec
  6. docker ps
  7. docker stop
  8. docker rm
  9. docker logs
  10. docker stats
  11. docker cp
  12. docker save
  13. docker inspect
  14. docker system
  15. docker volume
  16. docker network
  17. docker compose up
  18. docker compose down

Docker pull command tutorial: Download images with --platform, -q, and digests

docker pull downloads an image from an image repository; see Images for the concepts of images and tags.

Syntax

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

Options

OptionDescription
-a, --all-tagsDownload all tagged images in the repository
--platform stringSpecify the platform to download if the server supports multiple platforms
-q, --quietSuppress detailed output

Examples

Pull an image and pull it again

$ docker pull alpine:3.23
3.23: Pulling from library/alpine
5e9b4a97f639: Pulling fs layer
5e9b4a97f639: Download complete
97ab9557f126: Download complete
79dff55e92ba: Download complete
5e9b4a97f639: Pull complete
Digest: sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63
Status: Downloaded newer image for alpine:3.23
docker.io/library/alpine:3.23

$ docker pull alpine:3.23
3.23: Pulling from library/alpine
Digest: sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63
Status: Image is up to date for alpine:3.23
docker.io/library/alpine:3.23
  • The first pull shows layer download progress, the digest, and the Downloaded newer image status.
  • The next pull has the same digest and shows Image is up to date, without listing layer download progress again.
  • When you do not specify a registry, the full name in the output is docker.io/library/alpine:3.23.

Quiet mode and a missing tag

$ docker pull -q redis:8-alpine
docker.io/library/redis:8-alpine

$ docker pull nginx:9.99
Error response from daemon: failed to resolve reference "docker.io/library/nginx:9.99": docker.io/library/nginx:9.99: not found
  • -q suppresses detailed output such as download progress; the example prints only the full image name.
  • When tag 9.99 cannot be found, the daemon returns not found and lists the full image reference it could not resolve.

Select a platform and view platform variants

$ docker pull --platform linux/arm64 alpine:3.23
3.23: Pulling from library/alpine
197a036d7c64: Pulling fs layer
197a036d7c64: Download complete
4f0cdf9143b4: Download complete
8b7a0920489a: Download complete
197a036d7c64: Pull complete
Digest: sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63
Status: Image is up to date for alpine:3.23
docker.io/library/alpine:3.23

$ docker image inspect -f '{{.Os}}/{{.Architecture}}' alpine:3.23
linux/amd64

$ docker images --tree alpine:3.23
IMAGE                   ID             DISK USAGE   CONTENT SIZE   EXTRA
alpine:3.23             ff7f0c727dd7       26.6MB         8.21MB        
├─ linux/amd64          3d67941fed5a       12.9MB         3.85MB        
├─ linux/arm/v6         806bbcf86639           0B             0B        
├─ linux/arm/v7         b43a13ac240c           0B             0B        
├─ linux/arm64/v8       8793abc47938       13.5MB         4.19MB        
├─ linux/386            7811c228ca81           0B             0B        
├─ linux/ppc64le        cc3ef1f3240a           0B             0B        
├─ linux/riscv64        1e12543f1917           0B             0B        
└─ linux/s390x          ac74ebe0c48b           0B             0B
  • --platform linux/arm64 downloaded the arm64 layers, but the status still says Image is up to date: alpine:3.23 is a multi-platform image, so its name and digest have not changed; the local image now includes content for another platform.
  • As a result, docker image inspect still shows the local platform, linux/amd64, by default; to see other platforms, use docker images --tree below.
  • docker images --tree lists platform variants such as amd64 and arm64/v8; here, arm64/v8 uses 13.5MB of disk space.

Pin an image version with a digest

$ docker pull alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0
docker.io/library/alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0: Pulling from library/alpine
d0c1d894c237: Pulling fs layer
d0c1d894c237: Download complete
d836c7fd48f4: Download complete
047d62850641: Download complete
d0c1d894c237: Pull complete
Digest: sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0
Status: Downloaded newer image for alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0
docker.io/library/alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0

$ docker images alpine
IMAGE                                                                            ID             DISK USAGE   CONTENT SIZE   EXTRA
alpine:3.23                                                                      ff7f0c727dd7       26.6MB         8.21MB        
alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0   85fe1e81d675         13MB         3.94MB
  • Add @sha256: and the digest after the image name to identify the image by digest instead of using a mutable tag.
  • The Digest in the output matches the specified digest, and the status is Downloaded newer image.
  • docker images alpine lists both alpine:3.23 and the digest reference, with different IDs: this digest is for an earlier 3.23 version, while the 3.23 tag has since moved to a newer build. This is why you pin a version with a digest: tags move, but digests do not.

Exercises

Exercise: Pull the Alpine image in the prompt by digest, then view your local Alpine image list.

Answer 
docker pull alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0
docker images alpine

FAQ

Will running docker pull again download the image again?

If the image is up to date, the output shows Image is up to date; the example's digest and image reference also match the first pull.

How do I pin the version of an image I download?

Add @sha256: followed by the digest after the image name, for example, alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0.

What error appears when a tag does not exist?

In the example, nginx:9.99 returns not found, indicating that the registry cannot find that image reference.

After I specify --platform, will the image always appear for that platform in the inspect result?

After pulling with linux/arm64 in the example, docker image inspect shows linux/amd64; use docker images --tree to see the multiple platform variants listed for that image.

Updated October 26, 2026