Try 25 MB of US mobile proxy data free for 30 days.Start free trial
November 7, 202613 min read

Docker Proxy Settings: Daemon, CLI, Builds and Compose

Isometric layers representing Docker proxy settings

Docker has no single proxy switch. It has four separate places to set one, and each controls different traffic: the daemon (image pulls and pushes), the Docker CLI config (what containers and builds inherit), the build itself, and the running container. Set the wrong one and you get a timeout that looks like a network outage. This guide shows where each setting lives, the exact files and flags to use, how to handle SOCKS5 and credentials, and how to check that traffic really goes through your proxy.

TL;DR

  • Daemon proxy (image pull/push) is set in daemon.json or a systemd drop-in on Linux, and in Settings on Docker Desktop.
  • Container and build proxy comes from ~/.docker/config.json (proxies.default) or from -e and --build-arg flags.
  • Never put proxy credentials in ENV in a Dockerfile. Use build arguments or runtime environment instead.
  • SOCKS5 is not understood by containers through environment variables. Use socks5h:// on the daemon, or convert to an HTTP proxy for apps.
  • Verify with a one-line curl through the proxy from inside a container, and check the daemon separately with a pull.

Table of Contents

The four places Docker reads proxy settings

Before touching a file, decide which traffic you want to route. Docker's own documentation separates these cases clearly, and mixing them up is the most common cause of "I set the proxy and it still fails."

LayerWhat it controlsWhere you set it
Docker daemondocker pull, docker push, registry accessdaemon.json, systemd drop-in, or Docker Desktop settings
Docker CLI configProxy variables injected into containers and builds~/.docker/config.json
BuildRUN apt-get, pip install, npm install during docker build--build-arg or CLI config
Running containerOutbound requests from your app-e flags, Compose environment: or CLI config

The daemon can use a proxy configured through daemon.json (the recommended way) or through the --http-proxy and --https-proxy flags of dockerd, and that direct configuration takes precedence over environment variables. The CLI proxy settings work differently: they live in ~/.docker/config.json under proxies.default and are used to set proxy environment variables for containers and build arguments for builds. They do not configure the CLI or the daemon itself.

That last point trips people up. Editing config.json will never fix a failing docker pull. And a daemon proxy will never make your running container's requests.get() go through a proxy.

Configure the daemon proxy on Linux

On Linux you have two reliable options. Pick one and stay with it, so you always know where the setting lives.

Option 1: daemon.json

Edit /etc/docker/daemon.json:

{
  "proxies": {
    "http-proxy": "http://proxy.example.com:3128",
    "https-proxy": "http://proxy.example.com:3128",
    "no-proxy": "localhost,127.0.0.1,.internal.example.com"
  }
}

Then restart the daemon with sudo systemctl restart docker.

Option 2: a systemd drop-in

This is the method most guides show, and it works on every systemd distribution:

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://proxy.example.com:3128"
Environment="HTTPS_PROXY=http://proxy.example.com:3128"
Environment="NO_PROXY=localhost,127.0.0.1"
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

The official daemon proxy page describes both routes, including the reload and restart step. A shell that has HTTP_PROXY exported does not give the daemon a proxy: the daemon is a separate service with its own environment. One troubleshooting write-up describes exactly this failure: the shell has proxy variables, the daemon does not, and the daemon's direct connection is dropped by an egress firewall. The fix is giving the daemon its own configuration.

Check what the daemon actually loaded:

sudo systemctl show --property=Environment docker
docker info | grep -i proxy

Docker Desktop proxy settings

On macOS and Windows you do not edit systemd files. In Docker Desktop open Settings, go to Resources, choose Proxies, enable manual proxy configuration and enter the HTTP and HTTPS proxy details. Docker's Desktop settings reference explains the details that matter:

  • The Desktop proxy covers host-level traffic such as sign-in, the CLI and extensions.
  • It acts as a fallback for docker image pull only when the separate Containers proxy is not configured.
  • Desktop supports HTTP/HTTPS and SOCKS5 proxies, but SOCKS5 requires a Business subscription.

One more rule from the daemon proxy documentation: on Docker Desktop, proxy entries in daemon.json are ignored. Use the Desktop settings instead.

If you run Docker Desktop on a workstation and want a clean boundary between experiments and your host network, running workloads such as OpenClaw hosting in an isolated container shows how far container isolation can be pushed when you separate each service's network path.

Docker CLI config: proxies for containers and builds

If you want every container and build on a machine to inherit the same proxy, set it once in ~/.docker/config.json:

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

The supported keys are httpProxy, httpsProxy, ftpProxy, noProxy and allProxy, per the CLI proxy documentation. New containers started afterward receive HTTP_PROXY, HTTPS_PROXY and NO_PROXY (and lowercase variants) automatically. Existing containers do not change: recreate them.

To override for one container, pass the variables yourself:

docker run --rm \
  -e HTTP_PROXY=http://proxy.example.com:3128 \
  -e HTTPS_PROXY=http://proxy.example.com:3128 \
  python:3.12-slim python -c "import urllib.request as u; print(u.urlopen('https://api.ipify.org').read())"

Or bypass the config entirely for a single run with docker run --config /path/to/other/dir, which points the CLI at a different config directory.

Docker build proxy settings

A build runs commands in intermediate containers, so it needs the proxy during RUN apt-get update, pip install and the like. You do not want that proxy to stay in the final image.

The safe pattern is build arguments:

docker build \
  --build-arg HTTP_PROXY=http://proxy.example.com:3128 \
  --build-arg HTTPS_PROXY=http://proxy.example.com:3128 \
  --build-arg NO_PROXY=localhost,127.0.0.1 \
  -t my-scraper .

Docker predefines these proxy build arguments, so you do not need an ARG line in the Dockerfile. The CLI documentation says to avoid ENV for proxy settings in builds because it embeds the configuration in the image and can expose sensitive information, while proxy build-argument values are kept out of the build output. The original design discussion for this feature had the same goal: build-time arguments that are not persisted into the resulting image.

If you configured proxies.default in config.json, docker build picks these up for you and the flags above are only needed for overrides.

BuildKit and local proxies

A proxy running on your host at localhost:1080 is not reachable as localhost from inside a build. A Stack Overflow answer on SOCKS5 and builds notes that you need the IP of the docker0 interface (for example 172.17.0.1) or --network=host on Linux. On Docker Desktop, the hostname host.docker.internal generally points back to the host.

Docker Compose proxy environment

Compose has no proxy-specific keys. It uses the same mechanisms as the CLI: environment variables for running services and build arguments for images. If proxies.default is set in ~/.docker/config.json, services pick it up without any change. For explicit control, spell it out:

services:
  scraper:
    build:
      context: .
      args:
        HTTP_PROXY: ${PROXY_URL}
        HTTPS_PROXY: ${PROXY_URL}
    environment:
      HTTP_PROXY: ${PROXY_URL}
      HTTPS_PROXY: ${PROXY_URL}
      NO_PROXY: localhost,127.0.0.1,db,redis
    env_file:
      - .env

Keep the real value in a .env file that is git-ignored:

PROXY_URL=http://USERNAME:[email protected]:3128

Three habits prevent most Compose proxy bugs:

  1. List your service names in NO_PROXY. Compose services talk to each other by name (db, redis, api). Without them in NO_PROXY, internal calls go out to the proxy and fail.
  2. Use separate args and environment blocks. Build-time and run-time are different phases. Setting one does not set the other.
  3. Recreate after changes. Run docker compose up -d --force-recreate so containers pick up new variables.

A general walkthrough of corporate proxy setups for Docker shows the same Compose layout for environment variables and the same build-argument pattern.

Docker HTTPS proxy: the https:// mistake

The HTTPS_PROXY variable names the proxy used for HTTPS traffic. It does not mean the connection to the proxy itself must be HTTPS. For most proxies, the value should start with http://, even though the traffic it carries is TLS, which the client tunnels with CONNECT. One troubleshooting guide lists https:// in HTTPS_PROXY as a common mistake behind TLS handshake timeouts: use http:// unless the proxy terminates TLS itself.

If you want the longer explanation of what each scheme does at the protocol level, our HTTP vs HTTPS proxy decision rules cover it, and proxy authentication and 407 errors explains what happens when credentials are rejected.

Docker SOCKS5 proxy setup

SOCKS5 is where Docker gets awkward. Containers do not understand SOCKS5 through environment variables, and most applications expect HTTP and HTTPS proxy variables. You have three practical paths.

Three practical paths for Docker SOCKS5 proxies

1. Daemon level, for pulls and pushes. Use a systemd drop-in at /etc/systemd/system/docker.service.d/proxy.conf with HTTP_PROXY=socks5h://proxy-host:1080 and HTTPS_PROXY=socks5h://proxy-host:1080, then run sudo systemctl daemon-reload and sudo systemctl restart docker, as described here. The h in socks5h means the proxy resolves domain names. A practitioner note adds that if a Docker version rejects it, plain socks5 can be used instead.

2. Application level, inside the container. Most HTTP libraries accept a SOCKS5 URL in their own proxy option (for example socks5h://user:pass@host:port). This is the cleanest route for scrapers. Our guides on HTTPX proxy setup and aiohttp proxy setup show the exact syntax for Python.

3. Convert SOCKS5 to HTTP. Where a tool only reads HTTP_PROXY, a local converter such as Privoxy can turn a SOCKS5 upstream into an HTTP proxy. One practitioner report describes SOCKS5 in daemon.json as unstable, especially on Windows, and recommends this workaround.

Docker's experimental Sandboxes feature has its own setting, sbx settings set proxy.sandbox socks5://proxy.corp:1080. The upstream proxy page explains that socks5:// resolves DNS locally before handing off to the proxy, while socks5h:// delegates resolution to the proxy. That distinction matters for leaks, which we cover in our SOCKS5 vs HTTP proxy DNS tests.

Docker scraping proxies: separating the plumbing from the exit IP

Everything above is plumbing. For scraping, the second question is which IP your requests exit from. Datacenter ranges are easy for target sites to classify, which is why scraping teams move to real mobile carrier IPs for pages that block or throttle server traffic.

The cleanest Docker pattern for a scraping fleet:

  • Keep the daemon on your normal network or corporate proxy. Pulling images should not consume scraping bandwidth.
  • Give only the scraper containers the scraping proxy via environment: or the application's own proxy option.
  • Put the credentials in .env or Docker secrets, never in the image.
  • Use NO_PROXY for databases, queues and internal APIs.

This split also protects your metered data. When proxy usage is billed per byte, you want image layers and package installs on a different path, so only the target traffic counts.

Verify the proxy and troubleshoot

Test each layer separately.

# Daemon: does a pull work?
docker pull alpine:3.20

# Container: what IP does the outside world see?
docker run --rm curlimages/curl -s -x http://USERNAME:[email protected]:3128 https://api.ipify.org

# Inherited variables
docker run --rm alpine env | grep -i proxy

On Docker Desktop, the general FAQ says to check the most recent events in httpproxy.log. It lives at ~/Library/Containers/com.docker.docker/Data/log/host on macOS and %LOCALAPPDATA%/Docker/log/host/ on Windows.

SymptomLikely causeFix
docker pull times out, curl on host worksDaemon has no proxySet daemon proxy, restart Docker
Pull works, pip install in build failsBuild has no proxyAdd --build-arg or proxies.default
TLS handshake timeouthttps:// in HTTPS_PROXYUse http:// unless the proxy terminates TLS
407 Proxy Authentication RequiredWrong or unescaped credentialsURL-encode special characters in the password
Service-to-service calls fail in ComposeService names missing in NO_PROXYAdd them
502 or Forbidden from local Kuberneteskubernetes.docker.internal not in NO_PROXYAdd it, per the Desktop FAQ

The Kubernetes row comes from the Docker Desktop FAQ: with proxy variables set and that host missing from NO_PROXY, requests go to the proxy instead of the local cluster.

NO_PROXY syntax

The daemon proxy documentation lists what NO_PROXY accepts: IP address prefixes, domain names, a single asterisk to proxy nothing, and literal port numbers. A bare example.com matches the domain and all subdomains, while .example.com matches subdomains only. CIDR support varies by client library, so list the hostnames and prefixes your tools actually use.

Credentials

Proxy URLs often contain a username and password. The Docker CLI docs warn that environment variables are stored as plain text in a container's configuration, can be read through the remote API and can be committed into an image with docker commit. Keep credentials in a .env file outside version control, scope them per team member, and rotate them when someone leaves.

How we think about proxies in containers

Most Docker proxy problems are routing problems, not proxy problems. Teams spend an afternoon on systemd files when the real question is which traffic should leave through which IP. We separate the two: infrastructure traffic goes the normal way, and only the collection workload uses a proxy.

For that workload we built MaskLabs around real US mobile carrier IPs, city-level targeting across 46 cities, and a choice of sticky or rotating sessions. Containers fit this well. A scraper container needs one proxy URL and credentials, and it speaks HTTP, HTTPS or SOCKS5, whichever your library prefers. Credentials are self-serve, with team-level management, and a usage dashboard shows consumption because billing is per byte. You set it up without a sales call.

Our advice: put the proxy in the application's own configuration, pass credentials at runtime, and keep the daemon out of it.

Jon

Run your containers on real mobile IPs

If your Docker workloads scrape, monitor prices, verify ads or collect training data, you can point them at MaskLabs with one proxy URL in your Compose file. Our real carrier IPs in 46 US cities support geotargeted collection, with sticky or rotating sessions and HTTP, HTTPS or SOCKS5 access. The free trial comes with limited data, so you can try it in a container first.

Masklabs

Plans are published on the pricing page: Starter at $30 per month, Basic at $100 per month, Advanced at $500 per month and Scale at $1,000 per month, with prepaid data add-ons billed per GB. See US mobile proxies on real carrier IPs to get started. If your scraper is in Rust, C# or PHP rather than Python, our guides for Rust proxy requests, C# HttpClient proxies and PHP cURL proxies show the matching setup. For headless browsers in containers, see Chrome proxy flags.

FAQ

Why does my container ignore the proxy I set on the host?

Containers do not inherit your shell's environment. They get proxy variables from -e flags, Compose environment:, or the proxies.default block in ~/.docker/config.json. Set one of these and recreate the container, since existing containers keep their old variables.

Where do I put proxy settings for docker build?

Pass --build-arg HTTP_PROXY=... and --build-arg HTTPS_PROXY=..., or set proxies.default in the CLI config so builds pick them up automatically. Avoid ENV lines in the Dockerfile, because they embed the values, including any credentials, in the image.

Can Docker use a SOCKS5 proxy?

Yes, with limits. The daemon can use a socks5h:// value in a systemd drop-in, and Docker Desktop supports SOCKS5 on a Business subscription. Containers do not read SOCKS5 from environment variables, so configure SOCKS5 inside your application or convert it to an HTTP proxy first.

Do I need a proxy on the daemon and in the container?

Only if both need it. The daemon proxy handles image pulls and pushes. The container proxy handles your application's outbound requests. For scraping, it is usually best to give only the scraper containers the proxy.

Sources

Recommended