Pull Docker Images by Tag, Digest or Registry

A deploy fails because the image is not on the host, and docker image pull is the fix, but which tag, which digest and from where? This guide gets the image downloaded, checks the local result, and tells you when a tag, digest, registry host or platform is the right choice. Allow about ten minutes plus download time. The examples use Docker Community CLI 29.8.1 from the installed docker-ce-cli package, version 5:29.8.1-1~ubuntu.24.04~noble.

• You need: a working Docker Engine connection, and a registry account when the image is private.
• It changes: the local image store. It does not start a container. A pull can use a lot of bandwidth and disk space.
• Privileges: the normal command is unprivileged when your account can access the Docker socket. Do not add sudo automatically. If your installation requires it, use the same privilege consistently for later image commands.

1. Check the installed command

Confirm the client and its pull syntax before copying an image reference from a ticket or deployment file:

$ docker version --format '{{.Client.Version}}'
29.8.1
$ docker image pull --help
Usage:  docker image pull [OPTIONS] NAME[:TAG|@DIGEST]

Download an image from a registry

The shorter alias is docker pull. The full docker image pull form makes it clear that this belongs to Docker's image management commands.

2. Pull one tagged image

Start with an explicit tag when the image publisher documents one. This example uses the Docker Official Images namespace:

$ docker image pull debian:bookworm
bookworm: Pulling from library/debian
Digest: sha256:IMAGE_DIGEST_PRINTED_BY_DOCKER
Status: Downloaded newer image for debian:bookworm
docker.io/library/debian:bookworm

The digest and layer identifiers depend on the content, so your output will differ. On a second pull, Docker may report that the image is already up to date and reuse layers from the local content-addressable store.

If you omit the tag, Docker uses :latest:

$ docker image pull debian
Using default tag: latest

That default is fine for a quick test, but it is a moving name. For a repeatable build or service deployment, use the tag your project has selected, then consider pinning the resulting digest.

3. Verify what is now local

List the repository and tag you requested:

$ docker image ls --filter reference=debian:bookworm
REPOSITORY   TAG       IMAGE ID       CREATED       SIZE
debian       bookworm  4eacea30377a   ...           ...

Image ID, creation time and size vary with the image version and Docker's output formatting. The useful check is that the expected repository and tag are present. To inspect the exact reference and its metadata, use:

$ docker image inspect debian:bookworm

Inspect is read-only. Keep the image reference in the same form the consuming command uses, because a tag can later point at a different image.

4. Pin an image by digest

A tag is a name that can move. A digest identifies one image manifest, so it is the better boundary for a deployment that must fetch the same image again. Copy the digest printed by a trusted pull or release process, then use it after @:

$ docker image pull debian@sha256:REPLACE_WITH_A_64_HEX_DIGEST
docker.io/library/debian@sha256:REPLACE_WITH_A_64_HEX_DIGEST: Pulling from library/debian
Digest: sha256:REPLACE_WITH_A_64_HEX_DIGEST
Status: Image is up to date for debian@sha256:REPLACE_WITH_A_64_HEX_DIGEST

5. Pull from a private or different registry

An image reference can include a registry host and optional port. It is not a URL, so do not add https://:

$ docker image pull registry.example.test:5000/team/app:2026.09

For a private registry, authenticate with docker login using the registry's documented credentials flow before pulling.

Docker normally contacts registries over HTTPS. An HTTP or otherwise insecure registry must be explicitly allowed in the Docker daemon configuration. That weakens transport security and needs an administrator.

If the registry name, repository path or tag is wrong, check those values before escalating privileges. A permission error is not fixed by changing a tag to latest.

6. Choose a platform only when needed

Multi-platform images can publish different manifests for different CPU and operating-system combinations. Let Docker choose the host platform by default. If a build or test deliberately needs another supported platform, pass the one shown in the publisher's documentation:

$ docker image pull --platform linux/amd64 IMAGE_NAME:TAG

This can download an image that is not native to the host. Pulling it does not make every program inside it compatible with your hardware. Verify the target platform as part of the build or runtime workflow, rather than adding the option to every command by habit.

7. Limit scope and recover from mistakes

By default, one tagged image is pulled. --all-tags downloads every tagged image in a repository, which can use much more storage and bandwidth:

$ docker image pull --all-tags IMAGE_REPOSITORY

Use that option only when you genuinely need the complete repository. If a pull is taking too long, press Ctrl-C in the terminal that started it. The client stops the operation when its connection to the Engine is lost. Do not delete partially downloaded storage by hand.

A pull has no general undo command. If you downloaded the wrong completed image, identify it first:

$ docker image ls --filter reference=IMAGE_REPOSITORY
$ docker image rm IMAGE_REPOSITORY:WRONG_TAG

Common traps

• Cannot connect to the daemon. Check the Docker Engine service and socket access using your distribution's normal administration process. This is a host setup problem, not a registry image-name problem.
• Unauthorised or denied. Confirm the registry host and repository path, then authenticate with the registry's documented account. Avoid sharing the full error if it contains private repository names.
• Manifest unknown. The requested tag or digest is not published for that repository. Check the release record instead of guessing a nearby tag.
• Platform mismatch. Remove an unnecessary --platform override or select a platform the image actually publishes.
• Disk or network pressure. Stop the pull if necessary, then check space and the daemon's configured download limits. Do not respond by deleting random files under Docker's storage directory.