Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

docker pull cannot download images behind a corporate proxy

Errordocker pull from Docker Hub times out or cannot reach registry-1.docker.io

Short answer

docker pull is done by the daemon, not by your shell, so exporting HTTP_PROXY in the terminal changes nothing. Set the proxy in daemon.json or a systemd drop-in for the daemon, restart it, and set the CLI proxy file if containers and builds need it too.

  • Applies to Docker Engine 28, Ubuntu 24.04, systemd
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    See which proxy variables the daemon has. Empty output means the daemon connects directly.

    sudo systemctl show --property=Environment docker
  2. 2Match what you see, then jump to its fix

    1. 1Pull times out while curl through the proxy works in your shellThe daemon has no proxy configuredFix
    2. 2The drop-in file exists, and systemctl show prints no proxyYou use a systemd drop-in, but the environment was never reloadedFix
    3. 3docker pull succeeds, while apt-get or npm inside a build or container times outThe pull works, but containers and builds cannot reach the networkFix

What does the error look like?

  • docker pull from Docker Hub times out or cannot reach registry-1.docker.io
  • curl through the proxy works in your shell, while docker pull fails

Cause 1 of 3

The daemon has no proxy configured

1Check

Shell variables are not inherited by the service. The daemon reads daemon.json or its own service environment.

cat /etc/docker/daemon.json

2Fix

Add a proxies block to daemon.json (the documented method) and restart Docker.

{
  "proxies": {
    "http-proxy": "http://proxy.example.com:3128",
    "https-proxy": "http://proxy.example.com:3128",
    "no-proxy": "localhost,127.0.0.0/8"
  }
}
# then
sudo systemctl restart docker

3Verify

The pull goes through the proxy.

docker pull hello-world

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

You use a systemd drop-in, but the environment was never reloaded

1Check

A change to a unit or drop-in needs a daemon-reload before the restart takes it.

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

2Fix

Put the variables in the drop-in, reload systemd and restart Docker.

# /etc/systemd/system/docker.service.d/http-proxy.conf
[Service]
Environment="HTTP_PROXY=http://proxy.example.com:3128"
Environment="HTTPS_PROXY=http://proxy.example.com:3128"
Environment="NO_PROXY=localhost,127.0.0.1"
# then
sudo systemctl daemon-reload
sudo systemctl restart docker

3Verify

The variables show up in the service.

sudo systemctl show --property=Environment docker

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

The pull works, but containers and builds cannot reach the network

1Check

The daemon proxy covers image pulls only. Containers and RUN steps get proxy variables from the client config.

cat ~/.docker/config.json

2Fix

Add a proxies section to the client config. New containers and builds pick it up without a restart; existing containers do not change.

{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy.example.com:3128",
      "httpsProxy": "http://proxy.example.com:3128",
      "noProxy": "localhost,127.0.0.0/8"
    }
  }
}

3Verify

A new container shows the variables.

docker run --rm alpine env | grep -i proxy

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Keep the proxy in one place per layer: daemon.json for pulls, ~/.docker/config.json for containers.
  • Do not set proxy variables with ENV in a Dockerfile; the value would be baked into the image.
  • Add your private registry hosts to the no-proxy list.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.