Container Image Pull Time Calculator

Image reference:

Use an immutable digest when comparing estimates across change windows.

Compressed image size:

The changed-layer share is applied to this compressed payload.

Participating nodes:

Choose a whole-node count from 1 to 10,000.

nodes

Cached nodes:

Whole nodes are derived by rounding this share of the node count.

{{ formatNumber(cache_hit_percent, 0) }}%

New layer share:

This share affects transfer bytes, unpack work, and touched-layer setup.

{{ formatNumber(changed_layer_percent, 0) }}%

Shared registry bandwidth:

Prefer observed rollout-path throughput over interface line rate.

Mbps

Parallel pull lanes:

The model groups uncached nodes into concurrency-limited waves.

lanes

Unpack throughput:

Slow disks or crowded nodes can make local preparation dominate.

MiB/s

Layer count:

Touched layers are rounded up after applying the new-layer share.

layers

Layer setup cost:

Raise this when many small layers or slow storage metadata are visible in pull logs.

sec/layer

Per-lane bandwidth cap:

The cap is multiplied by active lanes, then limited by shared registry bandwidth.

Mbps

Retry reserve:

Zero keeps the base critical path unchanged.

Download/unpack overlap:

Zero keeps the conservative serial-phase model.

Manifest check time:

Zero omits lookup overhead; parallel nodes pay this on the wave critical path, not as a serial node sum.

sec/node

Measure	Value	Planning meaning	Copy
{{ row.label }}	{{ row.value }}	{{ row.note }}

Wave	Nodes	Transfer	Network	Local	Reserve	Finish	Copy
{{ row.label }}	{{ row.nodes }}	{{ row.transfer }}	{{ row.network }}	{{ row.local }}	{{ row.reserve }}	{{ row.finish }}

Lever	Modeled change	Time saved	Operator note	Copy
{{ row.label }}	{{ row.change }}	{{ row.saved }}	{{ row.note }}

A container image can be ready on one node and still delay a rollout across a fleet. Each node may need to resolve the image manifest, download missing compressed layers, unpack them, and prepare local snapshots before a workload can start. The slowest chain of those tasks sets the pull portion of the change window.

Image size alone does not predict that window. Cache coverage decides how many nodes need bytes, layer reuse decides how much each cold node transfers, and pull concurrency divides those nodes into waves. Shared registry bandwidth can then become a queue: adding more simultaneous pulls helps only while the registry path and any per-lane cap can feed them.

Local preparation matters most when storage is busy, images contain many small layers, or extraction is slow. Some runtimes overlap download and unpack work, but the phases are not perfectly interchangeable. A retry allowance can protect a plan from transient failures without pretending that every retry will have the same cost.

Cold node: A participating node that must fetch the changed share of the image.
Pull wave: The group of cold nodes pulling concurrently within the selected lane limit.
Critical path: The sequence of transfer, local preparation, and reserve time that determines when the final wave finishes.

A digest is a stronger comparison anchor than a movable tag because it identifies immutable content. Even with a digest, this remains a planning estimate rather than a runtime guarantee. Scheduler timing, registry throttling, credential failures, node disk pressure, image garbage collection, and application startup can extend the real rollout beyond the modeled pull window.

How to Use This Tool:

Start with the rollout slice you are actually scheduling and measurements from the same registry-to-node path whenever they are available.

Enter an Image reference, preferably an immutable digest, and the Compressed image size in MiB or GiB. Use the registry payload rather than the expanded filesystem size.
Set Participating nodes, Cached nodes, and New layer share. Cache coverage is converted to a whole-node count, while the changed share controls bytes, unpack work, and touched-layer setup.
Enter sustained Shared registry bandwidth, the maximum Parallel pull lanes, per-node Unpack throughput, and the image Layer count. Observed pull logs are more useful than interface line rate.
Open Advanced only when the rollout needs a per-lane cap, retry reserve, download/unpack overlap credit, or manifest-check time. A zero per-lane cap leaves shared bandwidth as the only network ceiling.
Read the Estimated rollout pull window, then compare the modeled bottleneck and wave timings with recent node events before committing a change window.

Interpreting Results:

The rollout pull window ends when the final modeled wave finishes. The transfer total is fleet-wide traffic, while transfer per pulling node is the changed compressed payload each cold node receives. A fully reusable payload produces no transfer waves; cached nodes can still carry manifest-check time when that value is entered.

Registry/network means raw network time is more than 15% above local preparation time.
Unpack/setup means local preparation time is more than 15% above raw network time.
Balanced means neither side exceeds the other by that 15% separation.

Treat the optimization comparisons as sensitivity checks, not promised savings. Raising pull lanes can make no difference after shared bandwidth or a per-lane throttle becomes the limit.

Technical Details:

Container images are content-addressed collections of compressed layers. A node can reuse a layer whose digest is already present, so the modeled transfer is the changed share of the compressed image rather than its expanded root filesystem. MiB is converted to megabits with 1 MiB = 8.388608 megabits.

Formula Core:

The first equations reduce the fleet to cold nodes and a per-node payload, then split those nodes into concurrency-limited waves.

\begin{matrix} N_{cached} & = & round (N \times \frac{C}{100}) \\ N_{cold} & = & N - N_{cached} \\ P_{node} & = & S_{image} \times \frac{G}{100} \\ W & = & ⌈ \frac{N_{cold}}{\min (L, N_{cold})} ⌉ \end{matrix}

Here, N is participating nodes, C is cache coverage in percent, G is changed-layer share in percent, S is compressed image size in MiB, L is the pull-lane limit, and W is wave count. Cached nodes are rounded to the nearest whole node and bounded from zero through the participating-node count.

For a wave containing n nodes, effective bandwidth is the smaller of shared registry bandwidth and the combined per-lane capacity. When the per-lane cap is zero, shared bandwidth is used directly.

\begin{matrix} B_{wave} & = & \min (B_{shared}, n \times B_{lane}) \\ T_{network} & = & \frac{n \times P_{node} \times 8.388608}{B_{wave}} \\ T_{local} & = & T_{manifest} + \frac{P_{node}}{R_{unpack}} + N_{layers} \times T_{setup} \\ T_{wave} & = & (T_{network} - T_{overlap} + T_{local}) \times (1 + \frac{R}{100}) \end{matrix}

The overlap credit is the selected overlap percentage of the smaller of raw network time and unpack time. Touched layers equal the changed share of the layer count rounded upward, with a minimum of one whenever any payload remains. Retry reserve is added after overlap credit. Wave durations are summed because later waves wait for a lane.

Important container pull model boundaries
Input or rule	Boundary	Effect
Cache and changed share	0% to 100%, inclusive	Determines whole cached nodes and per-node transfer.
Download/unpack overlap	0% to 90%, inclusive	Credits only the smaller phase.
Retry reserve	0% to 200%, inclusive	Adds proportional time to each wave.
No changed payload	Changed share = 0%	Produces zero transfer waves.
Bottleneck label	Greater than 15% separation	Exactly 15% remains Balanced.

Durations retain full precision in the model and are rounded only for display. An image reference labels the estimate; it does not query a registry or verify that the named image exists.

Limitations:

The queue model covers manifest time, layer transfer, unpacking, setup, and an explicit retry reserve. It does not simulate orchestration or application readiness.

Bandwidth is treated as sustained aggregate throughput, without burst behavior, connection ramp-up, registry rate limits, or cross-zone variation.
Every cold node receives the same changed share and uses the same unpack rate; heterogeneous nodes need separate estimates.
Scheduler placement, rollout strategy, disruption budgets, init work, probes, and application startup remain outside the pull window.
Validate important plans against an observed rollout of the same digest and node class.

Worked Examples:

One capped lane with partial layer reuse

A 1,024 MiB image with a 25% changed share leaves 256 MiB to transfer to one cold node. With a 200 Mbps lane cap, 128 MiB/s unpack rate, two touched layers at 0.25 seconds each, 0.5 seconds of manifest time, 50% overlap, and 10% retry reserve, the verified estimate is about 14.0 seconds. The result is network-bound because the raw transfer phase exceeds local preparation by more than 15%.

References:

The OpenContainers Image Manifest Spec, Open Container Initiative, November 2025.
The OpenContainers Layer Spec, Open Container Initiative, November 2025.
docker image pull, Docker Docs.
How to deploy a local Docker registry workflow, Simplified Guide.