Cannot Download Docker Images Behind a Proxy — How to Fix It

When working behind a corporate or network proxy, you might find that Docker can’t pull images from registries like Docker Hub.
You might see errors such as:

Error response from daemon: Get https://registry-1.docker.io/v2/: net/http: request canceled

or

x509: certificate signed by unknown authority

This happens because Docker doesn’t automatically inherit your system’s proxy settings — you must configure them manually.

---

1️⃣ Understanding the Problem

Docker uses the Docker daemon to pull images, not your shell session.
Even if you set HTTP_PROXY and HTTPS_PROXY in your terminal, the daemon itself may not have them.

The solution is to configure the proxy for the Docker daemon.

---

2️⃣ Configuring Proxy for Docker Daemon

Step 1 — Create Docker systemd directory

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

---

Step 2 — Add proxy configuration

Create a file:

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

Add your proxy settings:

[Service]
Environment="HTTP_PROXY=http://username:[email protected]:8080/"
Environment="HTTPS_PROXY=http://username:[email protected]:8080/"
Environment="NO_PROXY=localhost,127.0.0.1,.example.com"

---

Step 3 — Reload and restart Docker

sudo systemctl daemon-reexec
sudo systemctl restart docker

---

3️⃣ Configuring Proxy for Docker Client

If you run docker build and your build process needs internet access (e.g., apt-get or npm install inside Dockerfile),
you must pass proxy settings to the build environment:

docker build \
  --build-arg HTTP_PROXY=http://username:[email protected]:8080/ \
  --build-arg HTTPS_PROXY=http://username:[email protected]:8080/ \
  -t myimage .

Or inside docker-compose.yml:

build:
  context: .
  args:
    HTTP_PROXY: http://username:[email protected]:8080/
    HTTPS_PROXY: http://username:[email protected]:8080/

---

4️⃣ Common Issues & Fixes

Issue	Cause	Solution
“certificate signed by unknown authority”	Corporate proxy uses custom SSL cert	Add your CA cert to /etc/docker/certs.d/
Docker ignores proxy	Config not applied to daemon	Ensure /etc/systemd/system/docker.service.d/http-proxy.conf is correct and restart
Build works, but docker pull fails	Proxy set only in build args	Configure proxy in daemon settings

---

📌 Summary

When behind a proxy:

1. Set proxy for Docker daemon via systemd environment variables.
2. Restart Docker for changes to take effect.
3. Pass proxy settings to builds with --build-arg if needed.

With these steps, you can pull and build Docker images smoothly — even behind strict corporate firewalls.