Cannot Download Docker Images Behind a Proxy? Here’s How to Fix It

If you’re working behind a corporate firewall or proxy, you may run into a frustrating issue:

Docker cannot pull images from Docker Hub or other registries.

You might see errors like:

Error response from daemon: Get https://registry-1.docker.io/v2/: proxyconnect tcp: dial tcp: lookup proxy: no such host

In this article, you’ll learn why Docker fails behind a proxy, and how to configure it properly so you can download images without issues.

🧠 Why Docker Can’t Pull Images Behind a Proxy

Docker uses its own daemon (dockerd) to interact with container registries like Docker Hub. Even if your terminal or browser works through a proxy, Docker might not—unless it’s explicitly configured.

By default, the Docker daemon doesn’t inherit your system’s proxy settings.

✅ Step-by-Step: Configure Docker to Work Behind a Proxy

🔧 Step 1: Locate Docker’s Systemd Service File (Linux)

If you’re on Linux and using systemd (most common):

sudo mkdir -p /etc/systemd/system/docker.service.d

Create or edit the following file:

sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf

Add this content (adjust proxy URL):

[Service]
Environment="HTTP_PROXY=http://proxy.company.com:8080"
Environment="HTTPS_PROXY=http://proxy.company.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1,docker-registry.somecompany.com"

Save and exit the file.

🔄 Step 2: Reload and Restart Docker

sudo systemctl daemon-reexec
sudo systemctl daemon-reload
sudo systemctl restart docker

🧪 Step 3: Test It

Try pulling an image again:

docker pull nginx

✅ If successful, your proxy is correctly configured.

🖥️ On Windows or macOS (Docker Desktop)

  1. Open Docker Desktop
  2. Go to Settings > Resources > Proxies
  3. Set your HTTP_PROXY and HTTPS_PROXY values
  4. Click Apply & Restart

🧪 Verify Proxy Configuration

Check if Docker daemon received your environment settings:

docker info

You should see entries like:

HTTP Proxy: http://proxy.company.com:8080
HTTPS Proxy: http://proxy.company.com:8080

🚫 Still Not Working?

1. Is Your Proxy Authenticated?

If your proxy requires a username and password:

Environment="HTTP_PROXY=http://user:[email protected]:8080"

⚠️ Avoid storing plain credentials in config files. Consider using secrets or environment variables securely.

2. Use NO_PROXY Wisely

Ensure you add trusted domains and IPs to bypass the proxy:

localhost,127.0.0.1,.local,.example.com

3. DNS Errors?

Add DNS servers manually in Docker daemon config:

{
  "dns": ["8.8.8.8", "8.8.4.4"]
}

File location:

  • Linux: /etc/docker/daemon.json
  • Windows/macOS: Docker Desktop settings

Restart Docker after editing.

📝 Summary

TaskSolution
Docker can’t pull images behind proxySet proxy environment in Docker daemon
On LinuxCreate http-proxy.conf in /etc/systemd/system/docker.service.d/
On Docker DesktopUse GUI Settings → Proxies
Proxy auth neededInclude credentials in the proxy URL (carefully)
Docker DNS issuesAdd dns manually in daemon.json

✅ Conclusion

Docker doesn’t automatically use your system’s proxy settings, so it must be configured manually. Once you add the correct environment variables and restart the daemon, Docker will be able to pull images even behind a firewall.

With the right setup, working behind a proxy doesn’t have to slow you down.

Sharing Is Caring:

Leave a Comment