19.1.3 Pull CLI Command

The pull CLI command retrieves an image from a registry to the local daemon, and beyond its most basic usage, its flag set supports retrieving every tag for a repository at once, explicitly targeting a specific platform, and pulling by exact digest, while its progress output reveals specific, individually meaningful stages worth understanding when diagnosing a pull that seems unusually slow or stuck.

Basic usage and digest pulls

docker pull my-api:1.4.2
docker pull my-api@sha256:3f29a8c1d8e2b4f6a9c7d5e8b1f3a6c9d2e5f8b1a4c7d0e3f6a9c2d5e8b1f4a7

Pulling by digest rather than tag guarantees retrieval of an exact, specific, immutable piece of content, removing any ambiguity about what a mutable tag might currently point to, which is the same digest-preference principle covered for production deployment practices generally, directly applicable to the pull command itself.

Pulling every tag for a repository

docker pull --all-tags my-api

This retrieves every tag currently published for the my-api repository in a single command, which is useful for mirroring a repository's full set of published versions locally, but worth using deliberately rather than reflexively, since it can pull considerably more data than a single, specific tag would, particularly for a repository with a long history of published versions.

Targeting a specific platform explicitly

docker pull --platform=linux/arm64 my-api:1.4.2

This explicitly requests a specific architecture variant from a multi-platform manifest list, overriding whatever the host's own native platform would otherwise default to, useful for deliberately retrieving a non-native variant, perhaps for cross-platform testing, without needing to actually run on that target architecture at all.

Quiet mode for scripting

docker pull -q my-api:1.4.2

Quiet mode suppresses the normal, verbose progress output, printing only the final, resolved image reference once the pull completes, which is the more appropriate mode for a script that needs to confirm completion without needing or wanting the full, scrolling progress display cluttering its own output.

Understanding pull progress output stages

The default, verbose pull output shows each layer progressing through several distinct stages, and recognizing what each one represents clarifies exactly what a pull is currently doing at any given moment:

3f29a8c1: Pulling fs layer
3f29a8c1: Downloading [=====>    ]  45MB/98MB
3f29a8c1: Verifying Checksum
3f29a8c1: Download complete
3f29a8c1: Extracting [====>     ]  20MB/98MB
3f29a8c1: Pull complete

A layer stuck specifically at "Downloading" for an extended period suggests a network or registry-side bottleneck; one stuck at "Extracting" instead suggests the bottleneck has shifted to local disk I/O or CPU, since extraction is a local filesystem operation rather than a network one, which is a useful distinction when diagnosing exactly where a slow pull's actual bottleneck lies.

Layers downloading in parallel

Multiple layers shown progressing simultaneously in the output reflects the daemon's own default behavior of downloading several layers concurrently up to a configured limit, rather than strictly one at a time in sequence, which is generally beneficial for overall pull speed but means the visible progress lines do not necessarily represent a strict, sequential order of completion.

docker info --format '{{.RegistryConfig}}'

Resuming an interrupted pull

A pull interrupted partway through generally resumes efficiently on retry, since already-downloaded and verified layers are not re-downloaded from scratch, only the layers that had not yet completed when the interruption occurred:

docker pull my-api:1.4.2
# (interrupted)
docker pull my-api:1.4.2

This resumption behavior is one of the practical benefits of the layer-based, content-addressed image format: a partial, interrupted pull does not require discarding and restarting the entire operation, only the specific layers that had not yet finished.

Common pull failure messages and their meaning

manifest unknown: manifest unknown

pull access denied for my-api, repository does not exist or may require 'docker login'

toomanyrequests: You have reached your pull rate limit

Each of these specific messages points toward a distinct cause, a genuinely missing or mistyped reference, an authentication or authorization gap, or registry-side rate limiting respectively, and recognizing the specific wording directs troubleshooting efficiently toward the actual, correct category of cause rather than treating every pull failure as an undifferentiated, generic problem.

Common mistakes

• Using --all-tags reflexively rather than deliberately, pulling considerably more data than actually needed for the task at hand.
• Not distinguishing between a layer stuck downloading (network or registry-side bottleneck) versus stuck extracting (local disk or CPU bottleneck) when diagnosing a slow pull.
• Assuming an interrupted pull must be restarted entirely from scratch, rather than recognizing that already-completed layers are not re-downloaded on retry.
• Treating every pull failure message identically rather than reading the specific wording to direct troubleshooting toward the actual, correct category of cause.
• Not using quiet mode in scripts, leaving verbose, scrolling progress output cluttering automated pipeline logs unnecessarily.

The pull CLI command's flag set and progress output reveal considerably more useful detail than its most basic usage suggests, with --all-tags, --platform, and digest-based pulling addressing specific, deliberate scenarios, and the layer-by-layer progress stages and specific failure message wording both providing direct, actionable diagnostic information when a pull behaves unexpectedly.