Back to Blog

Why Is `docker pull` So Slow in China? Understanding How Docker Image Pull Works and Why It's Blocked

2025-07-16

🐌 Why Is docker pull So Slow in China?

Many developers in China are frustrated by painfully slow or failing docker pull commands — but why does it happen?

To understand the problem, we must first understand how docker pull actually works under the hood.

⚙️ How docker pull Works Behind the Scenes

When you run:

docker pull python:3.11

Docker performs a series of background steps:

  1. Resolve registry hostname
    Typically registry-1.docker.io

  2. Authenticate anonymously or via token

  3. Download manifest
    A JSON file describing the image layers

  4. Download each layer (blob)
    Dozens or hundreds of .tar.gz files
    Often from domains like cloudfront.net, fastly.net, or akamai.net

  5. Assemble image locally

💡 A single image may trigger 50+ HTTP requests to multiple domains.

🚧 Why Is It So Slow in China?

🔒 1. Docker Hub CDN Domains Are Throttled or Blocked

Docker uses global CDNs like:

  • cloudfront.net (Amazon)
  • fastly.net
  • akamai.net

These domains are:

  • ❌ Frequently blocked or reset by GFW
  • 🔁 Vulnerable to DNS pollution
  • 🐢 Extremely slow in mainland China

⚠️ 2. Multiple HTTPS Handshakes and Redirects

Each image layer may:

  • Require its own DNS resolution
  • Involve 302/307 redirects
  • Perform separate HTTPS handshakes

This adds latency and failure points.

🧱 3. VPNs and CI/CD Don’t Solve It

  • VPNs may bypass GFW but:
    • Are unstable
    • Not ideal for CI/CD runners
    • Unsuitable for air-gapped environments

💡 Real-World Developer Experience

docker pull python:3.11
# → stuck at 0.3 MB/s
# → timeout after 10 minutes

Even lightweight images like alpine can fail to pull.

✅ The Alternative: Use DockDepot

DockDepot solves this by:

  • Pre-pulling popular images
  • Packaging them as .tar archives
  • Hosting them over fast HTTPS CDN optimized for China
wget https://oecent.net/downloads/python_3.11.tar
docker load -i python_3.11.tar

💡 One request. One file. No redirects. No VPN.

🔍 Why .tar Works Better

  • ✅ Single file download
  • ✅ No layer-by-layer redirects
  • ✅ Works in schools, government, and secure networks
  • ✅ Compatible with wget, curl, or browser
  • ✅ Works offline and in CI/CD

🧠 Summary Comparison

Factordocker pullDockDepot
CDN Reliability in China❌ Poor✅ Optimized
Layer-by-layer downloads❌ Dozens per image✅ Single .tar file
GFW Compatibility❌ DNS reset / blocking✅ HTTPS direct access
CI/CD Compatibility⚠️ Requires VPN✅ Direct + scriptable
Offline Use⚠️ Requires export manually✅ Works out of the box

🚀 Try DockDepot Now

Visit https://oecent.net/tools/dockdepot
Search an image → Choose a tag → Download → docker load
A better Docker experience, especially in China.