Tutorials 4 min read

Docker Proxy Settings: Daemon, Builds and Containers Explained (2026)

Docker has three separate places a proxy can go, and setting the wrong one is why pulls work but builds don't. Here is each layer.

Docker proxy settings live in three different places, and each covers different traffic. The daemon uses one setting to pull images. Builds and running containers use another. Your application code may need a third. Most "Docker ignores my proxy" problems come from configuring one layer and expecting it to affect another. Here's each layer, what it controls and the exact config.

Layer 1: The Docker Daemon (Image Pulls and Pushes)

docker pull and docker push are performed by the daemon, not your shell, so your HTTPS_PROXY variable doesn't reach them. On Docker Engine 23 and later, set the proxy in /etc/docker/daemon.json:

{
  "proxies": {
    "http-proxy": "http://USERNAME:[email protected]:8080",
    "https-proxy": "http://USERNAME:[email protected]:8080",
    "no-proxy": "localhost,127.0.0.1,.internal.example.com"
  }
}

Then restart: sudo systemctl restart docker. On older engines, use a systemd drop-in instead:

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf <<'EOF'
[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"
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

Verify with docker info | grep -i proxy. On Docker Desktop, set the proxy under Settings, Resources, Proxies instead.

Layer 2: Builds and Containers via the Client Config

To give every new container and every build the proxy variables automatically, add a proxies block to ~/.docker/config.json on the machine running the docker command:

{
  "proxies": {
    "default": {
      "httpProxy": "http://USERNAME:[email protected]:8080",
      "httpsProxy": "http://USERNAME:[email protected]:8080",
      "noProxy": "localhost,127.0.0.1"
    }
  }
}

Docker then injects HTTP_PROXY, HTTPS_PROXY and NO_PROXY (and lowercase versions) into containers you start and into RUN steps during builds. No restart is needed. This is the setting that makes apt-get, pip and npm work inside a Dockerfile.

Layer 2b: Per-Build with Build Args

If you'd rather not set it globally, pass the proxy for a single build. HTTP_PROXY, HTTPS_PROXY and NO_PROXY are predefined build args, so you don't need to declare them with ARG:

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

Predefined proxy args are excluded from docker history, which is why they're safer than the alternative below.

Don't Put Proxy Credentials in ENV

Writing ENV HTTPS_PROXY=http://user:pass@... in a Dockerfile bakes your password into the image. Anyone who pulls the image can read it with docker inspect, and the container keeps routing through the proxy in production even when you didn't intend it to. Use build args or the client config for build-time access, and runtime environment variables for containers that genuinely need a proxy.

Layer 3: Runtime Containers and Compose

For a container whose application should use the proxy, for example a scraper, pass the variables at run time:

docker run --rm \
  -e HTTPS_PROXY='http://USERNAME-country-us:[email protected]:8080' \
  curlimages/curl -s https://api.ipify.org

In Compose, read them from a .env file that isn't committed:

services:
  scraper:
    build: .
    environment:
      HTTPS_PROXY: ${SCRAPER_PROXY}
      NO_PROXY: db,redis,localhost

Add service names like db and redis to NO_PROXY so traffic between your containers doesn't go out through the proxy. Forgetting this is a common source of strange connection errors and wasted bandwidth.

One IP per Container

Running several scraper replicas? Give each a distinct sticky session so they don't share or fight over IPs, for example SCRAPER_PROXY=http://USERNAME-country-us-session-worker1-time-30:[email protected]:8080 for one and worker2 for the next. The application still needs to honour HTTPS_PROXY; Python requests, Node with a proxy agent, curl and Go do. See the Node.js proxy guide for Node specifics.

Troubleshooting

  • Pull fails but builds work: the daemon isn't configured. Set Layer 1.
  • Pull works but RUN apt-get fails: the build isn't configured. Set Layer 2 or use build args.
  • Containers can't reach each other: missing NO_PROXY entries for service names.
  • 407 errors: wrong credentials or inactive plan; special characters in the password need percent-encoding. See how to fix proxy error 407.

Testing Each Layer Quickly

  1. Daemon: run docker info | grep -i proxy. You should see your HTTP and HTTPS proxy listed (credentials are masked).
  2. Containers: run docker run --rm alpine env | grep -i proxy. If the client config is set, the injected variables appear.
  3. Builds: add a temporary RUN wget -qO- https://api.ipify.org step to a test Dockerfile and build with --progress=plain --no-cache. The printed IP should be the proxy's.
  4. Application: run your container and check its logs or a test endpoint for the exit IP.

Testing layer by layer takes two minutes and tells you exactly which setting is missing.

Using NodeProxies with Docker

Use http://USERNAME:[email protected]:8080 at whichever layer you need. Image pulls and package installs are bandwidth-heavy, so route only what must go through the proxy, and consider datacenter proxies for that kind of bulk traffic. Tool-by-tool settings are in git, npm and pip behind a proxy. Register and see pricing.

FAQ

How do I make docker pull use a proxy?

Configure the daemon: a proxies block in /etc/docker/daemon.json (Engine 23+) or a systemd drop-in, then restart Docker.

Why doesn't my Docker build use HTTPS_PROXY from my shell?

Build steps don't inherit your shell environment. Pass --build-arg HTTPS_PROXY=... or set proxies in ~/.docker/config.json.

Is it safe to put proxy credentials in a Dockerfile?

No. ENV values are stored in the image. Use predefined build args or runtime environment variables instead.

NodeProxies

Ready to get started?

90M+ residential, mobile & datacenter proxies. Datacenter from $0.30/GB, residential from $0.42/GB. No contracts.

Create free account