What does the Docker daemon's `max-concurrent-downloads` setting control, and why does raising it often not speed a pull up?

### The two halves of a pull A pull has a network half and a local half, and they have different bottlenecks. The **network half** transfers compressed layer blobs. The daemon starts several transfers concurrently, bounded by `max-concurrent-downloads` (default 3). Any further missing layer sits in `Waiting`. The setting is daemon-wide and applies per pull operation, so it is a knob about how aggressively one host talks to a registry. The **local half** turns each downloaded blob into a usable read-only layer: verify its digest, decompress it, and unpack the tar stream onto the storage driver. Layers form a chain — each is applied on top of its parent — so extraction proceeds strictly in order. A layer can only be extracted once it has finished downloading *and* its parent has finished extracting. Downloads of later layers continue in the background while extraction works its way up the chain, but extraction itself never runs several layers in parallel. Setting it looks like this: ```json { "max-concurrent-downloads": 6, "max-concurrent-uploads": 5 } ``` Write that to `/etc/docker/daemon.json` and restart the daemon; it is not a per-`docker pull` flag. ### When more streams genuinely help Raising the limit helps when *each stream individually* is leaving capacity on the table: - **Latency-bound transfers.** A TCP connection to a registry 140 ms away spends much of its life waiting on acknowledgements. Three such connections may only reach a fraction of a 1 Gbit/s link; nine will do better. This is the classic case for turning the knob up on a node far from its registry. - **Per-connection shaping.** Some registries, proxies or object stores cap the throughput of a single connection. More connections then means more aggregate throughput. - **Many small layers.** An image with 24 modest layers finishes sooner with more of them in flight, because per-layer setup costs overlap. ### When it changes nothing - **The link is already saturated.** Extra streams divide the same bandwidth. If three transfers already sum to line rate, six will each run at half speed and finish at the same moment. - **One layer dominates.** A blob is transferred by a single stream. A Kotlin geospatial tile server whose runtime image is 1.87 GB with one 812 MB layer holding baked tile assets has a hard floor: that layer's transfer time is unaffected by concurrency, and everything else finishes long before it. - **The time is in `Extracting`.** Watch a slow pull and note which status the seconds accumulate under. Gzip decompression is single-threaded per layer, and unpacking writes many small files, so on a small burstable instance or a throughput-limited network disk, extraction can easily exceed download time. No download setting touches it. - **The registry is the constraint.** If the server side is slow or is shaping you, more concurrency can make things worse, and a fleet of nodes all doing it can turn a pull spike into a self-inflicted denial of service against your own registry. ### Where compression comes in The default layer media type is a gzipped tar. The OCI image spec also defines a **zstd** layer media type, and BuildKit can emit it (`--output type=image,compression=zstd`). Zstd typically decompresses several times faster than gzip at a comparable or better ratio, so it attacks the extraction half of the pull rather than the network half — which is exactly the half concurrency cannot help. The catch is compatibility: a zstd layer needs a runtime that understands that media type, so an older engine in the fleet cannot pull the image at all. That is a fleet-wide decision, not a per-image one. ### How to decide which knob you need Measure before turning anything. Time a pull on a representative fresh host, and note the split between `Downloading` and `Extracting`. Check whether one layer dwarfs the rest (`docker manifest inspect` shows compressed blob sizes without pulling). Watch CPU during extraction: a single core pinned at 100% while the network is idle is a decompression bottleneck, and the answers there are fewer or smaller layers, a faster codec, or faster hardware — not more sockets. A reasonable rule of thumb: leave the default alone unless you have a specific, measured reason. Six to ten is a common setting for nodes far from their registry on a fat link. Values in the dozens mostly buy connection churn and a noisier registry.