Pull Docker Images by Tag, Digest or Platform

You will finish with a repeatable way to download one Docker image, confirm the local result, 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 the 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. The pull command itself is not a system-file operation, but a Docker installation may require membership of its configured access group or an explicitly elevated invocation. Check that access before reaching for sudo.

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 available options on this installation are --all-tags, --platform and --quiet.

2. Pull one tagged image

A tag is convenient, but it is a name that can be moved in the registry. 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

The exact layer identifiers, digest and status vary. If no tag is supplied, Docker uses latest. Writing the tag explicitly makes that default visible in scripts and review. A later pull may say that the image is already up to date instead of downloading layers again.

This changes the local image store and consumes disk space. It does not start a container. There is no rollback that restores the downloaded network traffic. If the image is no longer wanted, inspect it first and remove it deliberately with docker image rm IMAGE; removal can fail or affect other local tags when the image is still referenced.

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 that the tag is present in the local image store. It does not by itself prove that the tag will resolve to the same content tomorrow.

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

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

The digest in this output is a content identifier. The placeholder above is intentional: copy the actual value printed by your registry rather than copying 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 obtained from a trusted registry or from the earlier inspection. Do not invent a digest and do not silently substitute a tag when pinning matters. A digest keeps the selected content fixed, so it will not automatically move to a newer image that includes later fixes. Updating a pinned deployment is an explicit change: select and review a new digest, then update the deployment reference.

5. Pull from another registry

A registry address appears 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

Use docker login registry.example.test:5000 first when the registry requires credentials. That command changes Docker's credential configuration and is security-sensitive: use the registry's approved authentication method, avoid putting passwords in shell history, and do not paste credentials into this pull command. Docker normally uses HTTPS for registry communication unless the daemon has been configured to allow an insecure registry. That daemon configuration is an administrative security boundary, not a pull-option shortcut.

6. Select a platform when the image is multi-platform

A multi-platform image can provide different manifests for different CPU and operating-system combinations. Let Docker choose for the host in the ordinary case. 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 required by the image and your later workload, 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

The output should match the platform you requested. If it does not, check the exact image reference and whether another local tag or image ID is being inspected.

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 consume substantial storage. It is usually a poor choice for a deployment or a routine update. Prefer a reviewed tag or digest. If an all-tags pull is already running and you need to stop it, press Ctrl-C. Docker terminates the pull when the client process is interrupted or its connection to the daemon is lost; check the local image list afterwards rather than assuming that nothing was stored.

8. Diagnose the common failures

A non-zero exit status means the requested pull did not complete successfully. Separate the likely causes:

• permission denied or a daemon connection error points to 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 means 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 point to network, proxy, registry or daemon configuration. Repeating the command may resume work, but it does not fix a consistently broken path.
• A successful pull followed by a container-start failure is a separate problem. First verify the image's platform, digest and local metadata, then investigate the container command.