How to Configure Docker Proxy for Daemon, Containers, and Builds

Sometimes due to network reasons (e.g., corporate NAT) you need a proxy. Docker's proxy configuration is a bit complex because there are three scenarios, but the principle is the same: use Linux environment variables like http_proxy.

Dockerd proxy

When you run docker pull, the daemon dockerd performs the operation, so the proxy must be set in the daemon's environment, which is controlled by systemd.

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

In proxy.conf (or any *.conf) add:

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

Replace proxy.example.com:8080 with your actual proxy (e.g., a cntlm proxy).

Container proxy

For containers that need a proxy at runtime, configure ~/.docker/config.json. The following works for Docker 17.07+:

{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy.example.com:8080",
      "httpsProxy": "http://proxy.example.com:8080",
      "noProxy": "localhost,127.0.0.1,.example.com"
    }
  }
}

This is a user‑level configuration; you can also set environment variables with -e http_proxy=… when running a container. The config.json method is convenient for development, while explicit -e is better for CI/CD or production.

Docker Build proxy

During docker build the build environment does not inherit the user‑level config, so you must pass proxy arguments:

docker build . \
  --build-arg "HTTP_PROXY=http://proxy.example.com:8080/" \
  --build-arg "HTTPS_PROXY=http://proxy.example.com:8080/" \
  --build-arg "NO_PROXY=localhost,127.0.0.1,.example.com" \
  -t your/image:tag

Note: both docker run and docker build are isolated from the host network by default. A proxy on localhost:3128 will not work unless you add --network host. Usually you need an external IP and the proxy must run in gateway mode.

Apply changes

After editing the daemon configuration, reload systemd and restart Docker:

sudo systemctl daemon-reload
sudo systemctl restart docker

Dockerd proxy changes require a daemon reload and Docker restart, while container and build proxy changes take effect immediately for subsequent runs.