Skip to content
Get Started
G2G2
4.7/5
Excellent
Trustpilot

How to use a proxy with Docker

To send a container's traffic through CleanProxies, pass the proxy as an environment variable: docker run -e HTTPS_PROXY=http://USERNAME:PASSWORD@HOST:PORT ..., or set it once for all new containers in ~/.docker/config.json under proxies.default. The daemon proxy (for image pulls) and build-time --build-arg are separate settings.

Try Now for $4.99Continue with Google
  • Session Control
  • High Speed
  • Privacy First

What you need

"Docker proxy" means three different things: the proxy your containers use when they run, the proxy used while an image builds, and the proxy the Docker daemon uses to pull images. For scrapers and AI agents in containers, the first one is what routes their requests through a CleanProxies IP; the other two only matter on networks that need a proxy to reach registries or package mirrors.

Your credential line

From the dashboard's proxy manager: host (or IP), port, username and password. Convert lists with the proxy list formatter.

Docker ready

  • Docker Engine or Docker Desktop. The proxies key in daemon.json needs Docker Engine 23.0 or later.
  • A container app that reads HTTPS_PROXY (curl, wget, Python Requests and Go do; some runtimes need their own proxy setting).

Which proxy fits Docker?

Both products use the same setup in Docker. What changes is how long an IP stays with you.

Static ISP Proxies

Best fit

Recommended for most container workloads. Each dedicated US ISP IP stays fixed with unlimited bandwidth and threads, so a fleet of containers can run around the clock without counting GB. Give each container its own IP when every worker should keep a stable identity.

starting from$0.75/IP

Dedicated static IPs registered to US and Canadian ISPs. The address stays the same for as long as you hold it, with unlimited bandwidth and HTTP(S) or SOCKS5 access.

Buy NowSee Static ISP Proxies features

Rotating Residential Proxies

Also works

Use rotating residential when containers scrape at scale across many sites and countries: pass a rotating line and each new connection can leave from a different IP, or a sticky line when a worker needs one IP for 5 minutes up to 24 hours. Keep image pulls and package installs off it, since residential is billed per GB.

starting from$0.63/GB

Residential IPs in 190+ countries with country, state and city targeting. Rotate on every request or hold a sticky session for up to 90 minutes; GB never expire.

Buy NowSee Rotating Residential Proxies features
credentials

Your CleanProxies credentials

Every product connects over HTTP(S); static ISP and ISP subnet proxies also run SOCKS5 and IP whitelisting. This is what the dashboard gives you to paste into Docker.

Static ISP and ISP subnetHTTP(S)SOCKS5IP whitelist
IP:PORT:USER:PASS

One line per dedicated IP. With IP whitelisting on, the line is just IP:PORT and no password is sent.

Rotating residential and mobileHTTP(S)User:pass
HOST:PORT:USER:PASS

Generated in the proxy manager. The username carries the location and session you pick, so generate a new list to change them.

As a URL, for code and most toolshttp://USERNAME:PASSWORD@HOST:PORTsocks5://USERNAME:PASSWORD@HOST:PORT

Use http:// even for HTTPS websites; the TLS session still runs end to end. The socks5:// form is for static ISP and ISP subnet proxies.

How to set up CleanProxies in Docker

Four steps, then check the exit IP with the free proxy checker.

  1. 1

    Build the proxy URL

    Turn your dashboard line into http://USERNAME:PASSWORD@HOST:PORT. With an ISP proxy on IP whitelisting, authorize the Docker host's public IP and use http://IP:PORT, which keeps credentials out of your configs.

  2. 2

    Test with one container

    Export the URL in your shell as HTTPS_PROXY, then run docker run --rm -e HTTPS_PROXY curlimages/curl -s https://api.ipify.org. A bare -e HTTPS_PROXY copies the value from your shell.

  3. 3

    Set it for your stack

    Add the variables to ~/.docker/config.json for every new container, or to the environment: of the services in your Compose file.

  4. 4

    Keep internal traffic direct

    Put localhost, 127.0.0.1 and your Compose service names in NO_PROXY so containers still reach your database, queue and each other directly.

copy & paste

Docker proxy examples

Replace the highlighted placeholders with the values from your dashboard. Pick an example to see its code.

Docker + CleanProxies

Proxy for your containers

In ~/.docker/config.json, the proxies.default object sets HTTP_PROXY, HTTPS_PROXY and NO_PROXY (upper and lower case) in every container you create from then on, and passes them as build args. In Compose, set the variables per service and keep the URL in a .env file next to compose.yaml as HTTPS_PROXY=http://USERNAME:PASSWORD@HOST:PORT.

~/.docker/config.jsonJSON
{
  "proxies": {
    "default": {
      "httpProxy": "http://USERNAME:PASSWORD@HOST:PORT",
      "httpsProxy": "http://USERNAME:PASSWORD@HOST:PORT",
      "noProxy": "localhost,127.0.0.1"
    }
  }
}
  • Docker stores these values in plain text in the container's configuration, where docker inspect shows them. Treat the Docker host like any other place that holds your proxy password.
fix it fast

Troubleshooting Docker proxy errors

Verify your exit IP

Run a throwaway container that prints its exit IP; it should match your proxy, not the Docker host. Run it once without -e to compare.

Open What is my IP? through the proxy to see the address and headers a website receives, or paste up to ten lines into the free proxy checker to test connectivity, latency and exit IP.

Still stuck? Our 24/7 support team answers fast: contact us with the error and the line you used (leave the password out).

Docker error fixes
  • The container still shows the host's IPWhy: The app inside ignores proxy environment variables, or the container was created before you edited config.json.Recreate the container, then check docker exec <name> env | grep -i proxy. If the variables are there, configure the proxy in the app itself (see the Node.js or Python Requests guides).
  • Containers can't reach the database or each otherWhy: Requests to service names are sent to the proxy, which can't reach your Docker network.Add the service names, localhost and 127.0.0.1 to NO_PROXY / noProxy.
  • 407 Proxy Authentication RequiredWhy: A password character such as @ or # breaks the proxy URL, or the variable was quoted wrongly in YAML.Percent-encode special characters (@ becomes %40) and keep the value in a .env file instead of inline.
  • daemon.json proxy has no effectWhy: Docker Desktop ignores it, or Docker wasn't restarted.On Docker Desktop use Settings → Resources → Proxies. On Linux, restart the daemon after editing.
  • UDP or QUIC traffic leaves directWhy: Proxy variables only cover HTTP(S) clients, and CleanProxies proxies carry TCP only.Keep scrapers on HTTP(S) over TCP; UDP isn't supported through the proxy.

Docker proxy guides

Setup guides and best practices from the CleanProxies blog.

Get the latest insightsAll Blogs

More integrations

Setup guides for tools people run next to Docker.

All integrations

Docker proxy FAQs

Straight answers about running CleanProxies in Docker.

Pass HTTPS_PROXY and HTTP_PROXY when you start it, for example docker run -e HTTPS_PROXY=http://USERNAME:PASSWORD@HOST:PORT, or set them for all new containers in the proxies.default section of ~/.docker/config.json.

Got more questions?All FAQs