2025 Guide to Docker Mirror Sources in China: Fix Pull Timeout in 5 Minutes

Introduction

Last Friday at 3 PM, I watched the cursor in my terminal blink for 10 minutes after running docker pull nginx:latest, only to be greeted with a bright red i/o timeout. To be honest, this wasn’t the first time. Since June this year, it’s been happening more frequently—my network connection was fine, web pages loaded instantly, but Docker images just wouldn’t pull.

After searching through online tutorials, I found that the recommended Alibaba Cloud and NetEase Cloud mirror sources didn’t work even after configuration. Later I discovered that on June 6, 2024, almost all domestic Docker Hub mirror accelerators went down—Alibaba Cloud, Tencent Cloud, Baidu Cloud, plus university mirrors, either shut down entirely or became internal-only.

You know that feeling? Following a pile of 2023 tutorials promising “perfect solution for slow Docker pulls,” configuring daemon.json, restarting Docker, and running docker pull again with high hopes, only to face another timeout. Pretty frustrating.

The good news is, some community-maintained mirror sources are still alive and working. In this article, I’ll tell you which Docker mirror sources still work in December 2025, how to configure daemon.json, and how to troubleshoot problems. Let’s get started.

Why Did Docker Mirror Sources Fail Massively?

Before jumping to solutions, I think it’s worth explaining what happened. After all, the Alibaba Cloud mirror you were using just fine couldn’t have died for no reason.

June 6, 2024 was the turning point. Starting that day, almost all mainstream Docker Hub mirror acceleration services in China announced service termination or restrictions. Mirror sources from tech giants like Alibaba Cloud, NetEase Cloud, Tencent Cloud, and Baidu Cloud all failed overnight. Even university-maintained mirrors from Nanjing University, Shanghai Jiao Tong University, and USTC shut down or switched to campus-only access.

Honestly, I was quite surprised when I heard the news. These mirrors had been running for years, and suddenly they were gone. Later I learned it was due to dual pressure from policy and costs—compliance considerations on one hand, and the expense of maintaining a highly available mirror service on the other.

If you try accessing these old mirrors now, you’ll either get a 404 or a connection timeout. If your daemon.json still has registry.cn-hangzhou.aliyuncs.com or hub-mirror.c.163.com configured, that configuration is basically useless.

What about connecting directly to Docker Hub? Technically possible, but you know how it is—directly accessing Docker Hub from China is painfully slow. Pulling a few hundred MB image takes at least half an hour, with timeout being the norm.

Still-Working Mirror Sources in December 2025

Don’t worry, though the big-name mirrors are down, some community members and individuals are quietly maintaining free Docker mirror acceleration services. I recently tested a bunch and compiled this list of mirrors still working as of December 2025.

Available Mirror Sources

Top picks: From my testing, Xuanyuan Mirror and DaoCloud are quite stable. The free version of Xuanyuan Mirror at docker.xuanyuan.me is already pretty fast, but if you need more stability, try registering for the pro version.

Usage Reminders

1. These are community-funded services. Unlike Alibaba Cloud or Tencent Cloud backed by big companies, these mirrors could go down anytime due to cost pressure. Use them responsibly, don’t abuse.

2. Not all images can be accelerated. Some mirrors only provide common base images (like nginx, mysql, redis) or have whitelist restrictions. If you timeout pulling an obscure image, it’s not the mirror’s fault—try another mirror or connect directly to Docker Hub.

3. Configure multiple mirrors. daemon.json supports multiple registry-mirrors, and Docker will try them in order. If the first fails, it automatically falls back to the second, improving success rate.

By the way, I found these mirror addresses from the dongyubin/DockerHub project on GitHub. This repository continuously updates available mirror source lists—worth bookmarking.

Step-by-Step daemon.json Configuration

Alright, with the mirror addresses in hand, next comes configuration. It’s actually simple—just edit a JSON file and restart Docker service. I’ll explain for the three mainstream systems.

Linux System (Most Common)

Most servers and dev machines run Linux, so this is the most important.

1. Create or Edit Configuration File

Configuration file location: /etc/docker/daemon.json (create it if it doesn’t exist)

sudo mkdir -p /etc/docker
sudo vi /etc/docker/daemon.json

2. Write Configuration

Copy this JSON snippet—I’ve configured three mirrors as backups:

{
  "registry-mirrors": [
    "https://docker.xuanyuan.me",
    "https://docker.m.daocloud.io",
    "https://docker.1ms.run"
  ]
}

Save and exit (in vi editor, press ESC then type :wq and hit enter).

3. Restart Docker Service

sudo systemctl daemon-reload
sudo systemctl restart docker

The first command reloads systemd configuration, the second restarts Docker. Both must be executed, otherwise the configuration won’t take effect.

macOS System (Docker Desktop)

If you’re on Mac, Docker Desktop provides GUI configuration, which is simpler.

1. Open Docker Desktop Settings

Click Docker icon in menu bar → Settings (or Preferences)

2. Find Docker Engine Configuration

Select Docker Engine from the left menu, you’ll see a JSON editor.

3. Modify JSON Configuration

Add the registry-mirrors field in the JSON configuration (remember to add comma if there are other configs):

{
  "registry-mirrors": [
    "https://docker.xuanyuan.me",
    "https://docker.m.daocloud.io"
  ],
  "other-existing-configs": "keep unchanged"
}

4. Apply and Restart

Click the Apply & Restart button in the bottom right, Docker will automatically restart and apply the configuration.

Windows System (Docker Desktop)

Windows configuration is almost identical to macOS, also through Docker Desktop GUI.

1. Open Settings

Right-click Docker icon in taskbar → Settings

2. Enter Docker Engine

Select Docker Engine from the left menu

3. Modify JSON Configuration

Same as macOS, add the registry-mirrors field, configuration content is identical.

4. Apply and Restart

Click Apply & Restart, wait for Docker to restart.

Configuration Notes

• JSON format must be correct. Most common error is extra or missing commas. Suggest checking with a JSON validation tool.
• Don’t configure failed mirror sources. If your daemon.json still has Alibaba Cloud or NetEase Cloud addresses, delete them—they’re useless now.
• Configure multiple backups. As mentioned, single mirrors might be unstable, having 2-3 backups improves success rate.

Verify Configuration Works

After configuration, don’t rush to pull images—verify the configuration is working first. Otherwise if something’s wrong, you’ll have to troubleshoot again.

Method 1: Check with docker info Command

The quickest verification is running docker info command and finding the Registry Mirrors line.

docker info | grep -A 5 "Registry Mirrors"

If configured successfully, you should see output like this:

Registry Mirrors:
  https://docker.xuanyuan.me/
  https://docker.m.daocloud.io/
  https://docker.1ms.run/

See your configured mirror addresses? If yes, configuration is working. If not, check if daemon.json format is correct and Docker service is restarted.

Method 2: Actually Pull an Image

Just checking configuration isn’t enough—try actually pulling an image to see the speed.

docker pull nginx:latest

I chose nginx because it’s the most common base image, almost all mirrors have it.

If configured successfully, you should see the progress bar flying, finishing in tens of seconds (nginx image is about 100+ MB). Compared to the previous 10-minute timeout, much faster, right?

I just tested—using Xuanyuan Mirror to pull nginx took less than 30 seconds from 0 to 100%. Pretty solid speed.

What If It’s Still Slow?

If it’s still slow or timing out after configuration, don’t panic—check the troubleshooting section below.

Troubleshooting Common Issues

Even with correct configuration, you might encounter various weird problems. I’ve compiled the pitfalls I’ve encountered and their solutions, hoping to save you some trouble.

Issue 1: docker info Doesn’t Show Mirror Sources

Symptom: Running docker info | grep "Registry Mirrors" outputs nothing, or still shows empty.

Possible Causes and Solutions:

1. daemon.json format error - Most common cause. JSON format is very strict, one extra or missing comma breaks it.

   • Solution: Use tools like JSONLint to check your daemon.json format.
   • Common mistakes: Extra comma after last array element, or unclosed curly braces.

2. Docker service not restarted - Configuration changes don’t take effect without restart.

   • Solution: Linux systems run sudo systemctl restart docker, Docker Desktop users click Apply & Restart.

3. File permission issues - daemon.json file permissions are wrong, Docker can’t read it.

   • Solution: Run sudo chmod 644 /etc/docker/daemon.json to fix file permissions.

Issue 2: Still Timing Out After Configuration

Symptom: docker info shows mirror sources configured successfully, but docker pull still times out.

Possible Causes and Solutions:

1. Image not in accelerator whitelist - As mentioned, not all images can be accelerated.

   • Solution: Try pulling common images like nginx, redis for testing. If those work, configuration is fine—switch mirrors or use a proxy.

2. Mirror temporarily unavailable - Community-maintained mirrors might be temporarily down due to traffic or maintenance.

   • Solution: Configure multiple mirrors in daemon.json so Docker auto-falls back. Or wait a bit and retry.

3. Local network issues - Firewall, proxy settings, DNS resolution can all cause problems.

   • Solution: Try ping docker.xuanyuan.me to see if it’s reachable, check firewall rules.

Issue 3: Docker Service Restart Fails

Symptom: After running systemctl restart docker, you get errors and Docker won’t start.

Possible Causes and Solutions:

1. daemon.json error preventing Docker startup - JSON format errors prevent Docker service from starting.
   • Solution: Check Docker logs journalctl -u docker.service for error messages.
   • Emergency fix: Rename or delete daemon.json, restart Docker to restore service, then slowly troubleshoot configuration.

sudo mv /etc/docker/daemon.json /etc/docker/daemon.json.bak
sudo systemctl restart docker

Issue 4: Some Special Images Won’t Pull

Symptom: Common images (nginx, redis) pull fine, but certain project private images or specific registry images won’t pull.

Solutions:

• Mirror accelerators only work for public images on Docker Hub. If your image is on a private registry (like gcr.io, quay.io), accelerators can’t help.
• In this case, consider:
  1. Configure HTTP proxy: Add http-proxy and https-proxy in daemon.json
  2. Use VPN or proxy services
  3. Find domestic mirror relay sites (some communities relay gcr.io images)

Alternative Solutions

If all methods above fail, consider:

1. Use Docker proxy - Configure HTTP proxy in daemon.json to let Docker access external networks through proxy.
2. Set up local private registry - Use tools like Harbor to build private registry, manually sync needed images.
3. Try at a different time - Sometimes it’s network peak hour issues, trying at different times might work.

Don’t panic when encountering issues—calmly analyze which step went wrong, troubleshoot step by step, and you’ll solve it.

Conclusion

Alright, that covers everything. Quick summary:

Key Points:

• After June 6, 2024, mainstream Docker mirrors from Alibaba Cloud, NetEase Cloud, Tencent Cloud all failed
• Currently working mirrors are mainly community-maintained, like Xuanyuan Mirror, DaoCloud
• Configuration method is modifying daemon.json file, adding registry-mirrors config, then restarting Docker
• Remember to configure multiple mirrors as backups to improve success rate
• When troubleshooting, first check JSON format, Docker service status, network connection

While these community mirrors aren’t as stable as the old big-name ones, they at least solve the urgent problem. Honestly, I don’t know how long these mirrors will last, so I suggest bookmarking that GitHub project (dongyubin/DockerHub)—it continuously updates available mirror source lists.

If this article helped you solve Docker image pulling slowness, feel free to share it with other friends also troubled by this issue. If you encounter problems, welcome to leave comments—I’ll reply when I see them.

One last reminder: treasure these community-funded free resources, don’t abuse them. Everyone’s having a tough time.

9 min read · Published on: Dec 17, 2025 · Modified on: Dec 26, 2025

Easton

Technology