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

Sometimes due to network reasons like corporate NAT you need a proxy. Docker's proxy configuration is a bit complex because there are three scenarios, but they all rely on Linux http_proxy environment variables.

Dockerd Proxy

When you run docker pull, the daemon dockerd performs the download, so the proxy must be set in the daemon's environment, which is managed by systemd. Therefore you configure the proxy in a systemd drop‑in file.

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

In proxy.conf (any *.conf file) 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 a reachable proxy, e.g., a local cntlm instance.

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 inject http_proxy via -e when running a container; choose the method that fits your scenario.

Docker Build Proxy

During docker build the build environment does not inherit the user‑level config, so you must pass proxy variables as build 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 that both docker run and docker build run in isolated networks; a proxy on localhost:3128 requires --network host, otherwise use an external IP and enable gateway mode.

Reloading Changes

After editing the systemd drop‑in, reload systemd and restart Docker:

sudo systemctl daemon-reload
sudo systemctl restart docker

Changes to container or build proxy take effect immediately for new containers; dockerd proxy changes need the daemon reload.