Docker Mirror Configuration

Pulling images from Docker Hub can be slow depending on your location. Configuring registry mirrors can significantly improve download speeds. This chapter covers common mirror configuration methods.

Why Use Registry Mirrors?

Docker Hub servers are located in specific regions. Users in other regions may experience:

• Very slow download speeds
• Connection timeouts
• Pull failures

Registry mirrors cache popular images on servers closer to your location, accelerating downloads.

Common Registry Mirrors

Mirror	URL	Notes
Docker Official China	https://registry.docker-cn.com	Official mirror
Google Mirror	https://mirror.gcr.io	Google Cloud

⚠️ Mirror availability may change. Configure multiple mirrors as fallbacks.

Linux Configuration

Edit daemon.json

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<EOF
{
  "registry-mirrors": [
    "https://registry.docker-cn.com",
    "https://mirror.gcr.io"
  ]
}
EOF

Restart Docker

sudo systemctl daemon-reload
sudo systemctl restart docker

Verify Configuration

docker info | grep -A 5 "Registry Mirrors"

Docker Desktop Configuration

Windows / macOS

1. Open Docker Desktop
2. Go to Settings → Docker Engine
3. Add registry-mirrors to the JSON configuration:

{
  "registry-mirrors": [
    "https://mirror.gcr.io"
  ]
}

4. Click "Apply & Restart"

Test Mirror Speed

# Remove local image first
docker rmi nginx:latest

# Pull and measure time
time docker pull nginx:latest

Alternative: Using a Proxy

If you have a proxy server, configure Docker to use it:

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/proxy.conf <<EOF
[Service]
Environment="HTTP_PROXY=http://proxy.example.com:8080"
Environment="HTTPS_PROXY=http://proxy.example.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1"
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

Self-Hosted Registry Mirror

For organizations, set up an internal registry mirror:

docker run -d \
  --name registry-mirror \
  --restart=always \
  -p 5000:5000 \
  -e REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io \
  registry:2

Common Issues

Mirror Not Working

# Verify config file format
cat /etc/docker/daemon.json | python3 -m json.tool

# Confirm Docker restarted
sudo systemctl restart docker

# Check Docker info
docker info

Some Images Not Accelerated

Third-party registries (e.g., ghcr.io, quay.io) don't go through Docker Hub, so mirrors won't help. Use a proxy for those.

Further Reading

• Docker Registry Mirror Documentation