docker pull cannot download images behind a corporate proxy
docker pull from Docker Hub times out or cannot reach registry-1.docker.ioShort 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.
Fix it fast
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 docker2Match what you see, then jump to its fix
- 1
Pull times out while curl through the proxy works in your shellThe daemon has no proxy configuredFix - 2
The drop-in file exists, and systemctl show prints no proxyYou use a systemd drop-in, but the environment was never reloadedFix - 3
docker pull succeeds, while apt-get or npm inside a build or container times outThe pull works, but containers and builds cannot reach the networkFix
- 1
What does the error look like?
docker pull from Docker Hub times out or cannot reach registry-1.docker.iocurl 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.json2Fix
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 docker3Verify
The pull goes through the proxy.
docker pull hello-worldConfirmed by docs.docker.com
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.conf2Fix
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 docker3Verify
The variables show up in the service.
sudo systemctl show --property=Environment dockerConfirmed by docs.docker.com
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.json2Fix
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 proxyConfirmed by docs.docker.com
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
Servers
docker pull says access denied or repository does not exist
Error response from daemon: pull access denied for <image>
Docker prints this when it cannot find the image under that name with your current credentials.
3 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
Cypress says the npm package is installed but the binary is missing
Cypress binary is missing after npm install in CI or in a Docker build
The npm package is only a launcher.
3 causes, each with a fix