How to Set Up a Proxy for Docker: Daemon, Desktop, Build and Containers

What a proxy changes and what it does not

A proxy changes only the network exit of the traffic you point at it. It does not change the terms of the registry or the images you pull, and Docker Desktop's own subscription rules stay the same: its documentation notes, for example, that SOCKS5 support requires a Business subscription. The Docker documentation also warns that proxy settings may contain sensitive information: environment variables can be read through the remote API or committed into an image, so do not bake a proxy with a password into an image you share.

• Sources:
• Docker docs: Configure the Docker client to use a proxy server
• Docker docs: Docker Desktop settings (Proxies)

Four places, four settings

Docker is several programs, and each reads its proxy from its own place. The daemon (dockerd) is the background service that downloads images, so docker pull uses the daemon's proxy. Docker Desktop on Windows and Mac has its own settings screen. A build runs in a separate build container and gets proxy values as build arguments. A container you run gets its proxy only from variables set inside it. Setting one place does not set the others, so find which of the four is failing: a pull that fails is the daemon or Desktop, a download that fails inside a Dockerfile RUN line is the build, and a program that cannot connect inside a running container is the container.

Pulling images on Linux: the daemon

On a normal Linux install the Docker documentation uses a systemd drop-in: a small file that adds environment variables to docker.service. Create /etc/systemd/system/docker.service.d/http-proxy.conf with a [Service] section and Environment lines for HTTP_PROXY, HTTPS_PROXY and NO_PROXY, then run systemctl daemon-reload and systemctl restart docker. NO_PROXY is a comma-separated list of addresses that should not use the proxy; keep localhost and 127.0.0.1 in it. In rootless mode the file is ~/.config/systemd/user/docker.service.d/http-proxy.conf and the commands take --user. The last command in the example prints the variables the service now has, which is how the Docker page suggests you verify it.

Special characters in the proxy value, such as #?!()[]{}, must be double escaped with %% according to the same page. So a password containing # is written with %%23 in this file, not %23 as in a plain command line. Use the proxy as http://, also in HTTPS_PROXY: the proxy address is the same, only the traffic it carries is encrypted.

• Sources:
• Docker docs: Daemon proxy configuration

The daemon with systemd: example

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf >/dev/null <<'EOF'
[Service]
Environment="HTTP_PROXY=http://USERNAME:PASSWORD@HOST:PORT"
Environment="HTTPS_PROXY=http://USERNAME:PASSWORD@HOST:PORT"
Environment="NO_PROXY=localhost,127.0.0.1"
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker
sudo systemctl show --property=Environment docker

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

The same thing in daemon.json

Instead of systemd you can put a proxies block into the daemon's configuration file, which is /etc/docker/daemon.json on Linux and C:\ProgramData\docker\config\daemon.json on Windows. The keys are http-proxy, https-proxy and no-proxy. Restart the Docker daemon after editing. If the file already has other settings, add the block inside the existing braces instead of creating a second set. Do not set the same proxy in both the drop-in and daemon.json: pick one.

• Sources:
• Docker docs: Daemon proxy configuration
• Docker docs: Daemon configuration

The same thing in daemon.json: example

{
  "proxies": {
    "http-proxy": "http://USERNAME:PASSWORD@HOST:PORT",
    "https-proxy": "http://USERNAME:PASSWORD@HOST:PORT",
    "no-proxy": "localhost,127.0.0.1"
  }
}

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

Docker Desktop (Windows and Mac)

1. Open Settings > Resources > Proxies

   Docker Desktop has two proxy settings. The Docker Desktop proxy covers the app itself (signing in, the CLI, extensions). The Containers proxy covers docker image pull, including Compose pulls. If the Containers proxy is not set, the Desktop proxy is the fallback for pulls.

2. Choose Manual configuration

   Enter http://HOST:PORT in both the Web Server (HTTP) field and the Secure Web Server (HTTPS) field. The exclusion list takes hosts and domains that should not use the proxy.

3. Type the username and password when asked

   For a proxy with Basic authentication, the documentation says Docker Desktop prompts for credentials and keeps them in the operating system's credential store. It does not say whether a username and password may also be written inside the URL fields, so use the prompt.

4. Apply and restart

   Click Apply, let Docker Desktop restart, then check with the commands in the check section below.

HTTP or SOCKS5

Docker Desktop supports HTTP/HTTPS and SOCKS5 proxies, but its documentation says SOCKS5 requires a Business subscription. The daemon page on Linux does not mention SOCKS at all. So for Docker choose HTTP when you generate the proxy, as the examples here do.

• curl proxy setup guide

• Sources:
• Docker docs: Docker Desktop settings (Proxies)
• Docker docs: Daemon proxy configuration

Proxy during docker build

A download inside a Dockerfile (for example RUN apt-get update or RUN npm install) runs in the build container. Docker has predefined build arguments for this: HTTP_PROXY, HTTPS_PROXY, FTP_PROXY, NO_PROXY and ALL_PROXY. You pass them with --build-arg and you do not have to declare them in the Dockerfile. They are left out of the build cache and docker history by default, but if your Dockerfile mentions them the proxy ends up in the cache. If you already have a proxies block in ~/.docker/config.json (next section), these arguments are filled in for you. Do not use the ENV instruction for a proxy: the Docker page recommends build arguments instead, because ENV is stored in the image.

• Sources:
• Docker docs: Build variables (proxy arguments)
• Docker docs: Configure the Docker client to use a proxy server

Proxy during docker build: example

docker build --build-arg HTTP_PROXY=http://USERNAME:PASSWORD@HOST:PORT \
  --build-arg HTTPS_PROXY=http://USERNAME:PASSWORD@HOST:PORT .

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

Proxy inside the containers you run

The Docker client can set the proxy variables inside every new container for you. Add a proxies block to ~/.docker/config.json on the machine where you run the docker command. When a container starts, Docker sets HTTP_PROXY, http_proxy, HTTPS_PROXY, https_proxy, NO_PROXY and no_proxy in it. The file takes effect without restarting Docker, but only for new containers and builds, not for containers that are already running. For a single container you can pass --env instead, as the second example shows. Programs inside the container still need to read these variables: curl and many tools do, some do not.

The same page warns that internal proxy addresses may not be reachable from a container, and that proxy values can be read from the API. Use a proxy address the container can reach.

• Sources:
• Docker docs: Configure the Docker client to use a proxy server

Proxy inside containers: ~/.docker/config.json

{
  "proxies": {
    "default": {
      "httpProxy": "http://USERNAME:PASSWORD@HOST:PORT",
      "httpsProxy": "http://USERNAME:PASSWORD@HOST:PORT",
      "noProxy": "localhost,127.0.0.1"
    }
  }
}

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

Proxy for one container: example

docker run --rm --env HTTPS_PROXY=http://USERNAME:PASSWORD@HOST:PORT curlimages/curl -s https://ipinfo.io/json

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

How to check that Docker uses the proxy

1. Daemon: check the variables

   On Linux run sudo systemctl show --property=Environment docker and look for HTTP_PROXY and HTTPS_PROXY. On Docker Desktop look at Settings > Resources > Proxies.

   • Linux proxy setup guide

2. Pull a tiny image

   Run docker pull hello-world. If it downloads, the daemon (or Desktop) reached the registry through the proxy. If it times out, test the proxy outside Docker with the curl command in the example.

3. Containers: print the variables

   docker run --rm alpine env | grep -i proxy shows the proxy variables a new container received from ~/.docker/config.json.

4. Check the exit address

   The curl command shows the IP, country and network that websites see through the same proxy. The guide on how to check your proxy's IP, country and ISP explains the fields.

   • how to check your proxy's IP, country and ISP
   • curl proxy setup guide

How to check that Docker uses the proxy: example

docker pull hello-world
docker run --rm alpine env | grep -i proxy
curl -x http://USERNAME:PASSWORD@HOST:PORT https://ipinfo.io/json

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

Common errors

• Pull times out after you edited the drop-in. You forgot systemctl daemon-reload and the restart, or the file name or [Service] line is wrong. Print the variables with systemctl show.

• 407 Proxy Authentication Required. The proxy rejected the username or password. In systemd and daemon.json files special characters need the %% form described above; copy the details again from My assets.

• The pull works but a RUN line in the Dockerfile cannot download. The build does not use the daemon's proxy: pass --build-arg or fill ~/.docker/config.json.

• A running container ignores the new config.json. It only applies to new containers; start a fresh one.

• Everything works except local services. Add them to NO_PROXY (localhost,127.0.0.1 and your internal domains).

• authentication required guide
• connection failed guide

• Sources:
• Docker docs: Daemon proxy configuration
• Docker docs: Configure the Docker client to use a proxy server

How to do it with Proxy302

Every command here needs only the host, port, username and password of a Proxy302 proxy. Rotating residential traffic is billed per GB and the exit country is set when you generate the proxy; HTTP is on port 2222 and SOCKS5 on port 3333 of proxy.proxy302.com. A static ISP IP stays fixed for the whole lease and does not rotate, which suits a tool that you want to always leave from the same address. HTTP or SOCKS5 is chosen when you buy, and one IP carries one protocol.

• rotating residential page
• SOCKS5 proxies page

• Sources:
• Proxy302 product facts and price list

How to do it with Proxy302: steps

1. Step 1

   Open the rotating residential page, choose the line, keep Protocol on HTTP (or choose SOCKS5), then click Review cost and generate.

2. Step 2

   Open My assets (the console page that holds everything you bought) and copy HOST, PORT, USERNAME and PASSWORD. The Connect page shows a ready example with your own endpoint.

3. Step 3

   Put the values into the commands above.

4. Step 4

   Confirm the exit with https://ipinfo.io/json through the proxy.

   • how to check your proxy's IP, country and ISP

5. Step 5

   From mainland China, start the helper tool from the Connect page first and keep it open while you use the proxy.

   • Helper tool guide

Prices and limits

The Budget line costs US$1.50 per GB, US$1.35 per GB in a 100 GB package and US$1.20 per GB at 300 GB. A static ISP IP costs US$0.50 for one day and US$7.99 for 30 days. There is no free trial, and the smallest purchase is 1 GB or one IP for one day. Which exit locations are available changes daily.

• Sources:
• Proxy302 product facts and price list

FAQ

Read next

Linux proxy setup

Set a proxy on Linux: http_proxy, https_proxy and no_proxy variables, making them permanent, the GNOME Network proxy panel, and proxy settings for apt and dnf.

curl proxy setup

Use an HTTP or SOCKS5 proxy with curl: -x, credentials, socks5h, environment variables, .curlrc and an exit check.

Check a proxy's IP, country and ISP

Check the exit IP, country and ISP your proxy really gives you in 30 seconds — and why IP databases disagree on the city. With our own test of three lookup services.

Fix ERR_PROXY_CONNECTION_FAILED

The ERR_PROXY_CONNECTION_FAILED error appears in Chrome and Edge when the browser cannot establish a connection with a proxy server.