Pull Docker Images by Tag, Digest or Platform

A tag is a name, and names can move, so the image you pull today may not be the image you pull next month. This guide shows how to run docker pull for one image, confirm what landed locally, and choose between a moving tag and an immutable digest. The examples match Docker Community Edition CLI 29.8.1, installed here as package docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble.

Allow about ten minutes for one image, plus download time.

• You need: the Docker CLI, a running Docker daemon, network access to the registry, and permission for your account to use that daemon.
• Check access before sudo. The pull itself is not a system-file operation, but a Docker installation may require membership of its configured access group or an explicitly elevated invocation.

1. Check the installed command

Start with read-only checks. They do not download anything and normally need no elevated privileges:

$ docker --version
Docker version 29.8.1, build 4a63305
$ docker pull --help
Usage:  docker pull [OPTIONS] NAME[:TAG|@DIGEST]

The installed manual describes docker pull as an alias for docker image pull. The name must identify an image repository and may include a tag or digest. The options available on this installation are --all-tags, --platform and --quiet.

2. Pull one tagged image

For a small, familiar smoke test, pull Docker's hello-world image:

$ docker pull hello-world:latest
latest: Pulling from library/hello-world
...
Status: Downloaded newer image for hello-world:latest
docker.io/library/hello-world:latest

Layer identifiers, digest and status vary. If you supply no tag, Docker uses latest, so write the tag explicitly to make that default visible in scripts and review. A later pull may say the image is already up to date instead of downloading layers again.

3. Verify the local image

Use the image listing as a quick checkpoint. The filter keeps unrelated local images out of the result:

$ docker image ls --filter reference='hello-world:latest'
REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
hello-world   latest    ...            ...            ...

Your image ID, creation time and size will differ. A row for the requested repository and tag confirms the tag is in the local image store. It does not prove the tag will resolve to the same content tomorrow.

For a more precise check, ask Docker for the image's repository digests:

$ docker image inspect --format '{{json .RepoDigests}}' hello-world:latest
["docker.io/library/hello-world@sha256:REPLACE_WITH_THE_DIGEST"]

A digest is a content identifier. The placeholder above is intentional: copy the actual value your registry prints, not an example digest from documentation.

4. Pull an immutable digest

Use a digest when a deployment or audit must refer to exactly one image manifest. A digest replaces the tag:

$ docker pull docker.io/library/hello-world@sha256:REPLACE_WITH_THE_DIGEST
docker.io/library/hello-world@sha256:REPLACE_WITH_THE_DIGEST: Pulling from library/hello-world
...
Digest: sha256:REPLACE_WITH_THE_DIGEST
Status: Image is up to date for docker.io/library/hello-world@sha256:REPLACE_WITH_THE_DIGEST

Replace the whole digest reference with a real value from a trusted registry or from the inspection above. Do not invent a digest, and do not quietly substitute a tag when pinning matters.

5. Pull from another registry

A registry address goes at the start of the image name and has no https:// prefix. For a private registry, use its host, optional port, namespace and repository:

$ docker pull registry.example.test:5000/team/app:2026-09
2026-09: Pulling from team/app
...
Status: Downloaded newer image for registry.example.test:5000/team/app:2026-09
registry.example.test:5000/team/app:2026-09

Run docker login registry.example.test:5000 first when the registry requires credentials.

6. Select a platform for multi-platform images

A multi-platform image can provide different manifests for different CPU and operating-system combinations. Normally, let Docker choose for the host. If you need a specific target, pass --platform:

$ docker pull --platform linux/amd64 hello-world:latest
latest: Pulling from library/hello-world
...
Status: Downloaded newer image for hello-world:latest
docker.io/library/hello-world:latest

Use the platform value your image and workload need, such as linux/amd64 or linux/arm64. Pulling a platform-specific variant does not make a program compiled for one architecture run natively on another. Check the selected result when it matters:

$ docker image inspect --format '{{.Os}}/{{.Architecture}}' hello-world:latest
linux/amd64

7. Pull every tag only with a clear reason

By default, Docker pulls one image. --all-tags requests every tagged image in a repository:

$ docker pull --all-tags registry.example.test:5000/team/app
Pulling repository registry.example.test:5000/team/app
...

This can download many images and use a lot of storage. It is usually a poor choice for a deployment or routine update. Prefer a reviewed tag or digest.

8. Diagnose the common failures

A non-zero exit status means the pull did not complete. Match the symptom to the likely cause:

• permission denied or a daemon connection error. Local Docker access or daemon state. Check docker info and your installation's service and group configuration.
• manifest unknown or a similar registry response. Usually the repository, tag or digest is wrong, unavailable, or not visible to your account. Recheck the full name and authenticate to the intended registry.
• Timeouts or failed layer downloads. Network, proxy, registry or daemon configuration. Repeating the command may resume work, but it does not fix a consistently broken path.
• A good pull, then a container-start failure. A separate problem. Verify the image's platform, digest and local metadata first, then investigate the container command.