How to Configure Proxies in Docker and Docker Compose

Docker proxy settings depend on which process needs internet access. Your application, an image build and the Docker daemon can each use different settings. A container’s successful HTTP request does not prove that image pulls or build steps use the same route.

Begin with a disposable curl container. Verify its outbound IP, then move the working settings to an application that explicitly supports them. This guide uses an HTTP forward proxy and the modern docker compose command. The downloadable files contain placeholders, not an operational proxy login.

Choose the process that needs a proxy

Traffic Setting location What to verify
Application requests inside a container Application options or container environment The actual client honors the settings.
Package downloads in Dockerfile RUN steps Build proxy arguments or a supported secret mount The package manager uses the route.
Image pulls and registry access Docker Engine daemon or Docker Desktop settings The registry is reachable by the backend.
Default variables for new containers and builds Docker client config.json proxies section The defaults reach newly created workloads.

The Docker client proxy reference explicitly separates container/build defaults from the daemon’s configuration. Keep that distinction in your troubleshooting notes: “curl in the container failed” and “docker pull failed” point to different processes.

Run a focused Docker Compose IP check

Download docker-proxy-compose.yaml and docker-proxy.env.example into the same folder. Copy the environment example to docker-proxy.env, replace its proxy URL, and protect that file if you add credentials.

PROXY_URL=http://proxy.example.com:3128

The core Compose pattern passes one supplied endpoint to both destination protocols:

services:
  ip-check:
    image: curlimages/curl:8.21.0
    environment:
      http_proxy: "${PROXY_URL:?Set PROXY_URL}"
      https_proxy: "${PROXY_URL:?Set PROXY_URL}"
      NO_PROXY: "localhost,127.0.0.1"
    command:
      - --silent
      - --show-error
      - --fail
      - --max-time
      - "30"
      - --noproxy
      - ""
      - https://api.ipify.org?format=json

The downloadable version also supplies uppercase variables and a connection timeout. Its explicit empty --noproxy argument prevents curl bypass rules from affecting this diagnostic request. The image uses the official curl 8.21.0 tag; test your chosen release and pin its digest for production. Keep your real application’s bypass list deliberate.

docker compose --env-file docker-proxy.env -f docker-proxy-compose.yaml config --quiet
docker compose --env-file docker-proxy.env -f docker-proxy-compose.yaml run --rm ip-check

The first command checks Compose configuration without printing expanded values; the second starts one disposable container. Read the JSON ip field and compare it with the expected proxy exit. If Docker must pull the curl image first, that pull uses Docker’s registry connection, before curl’s container environment can take effect.

The required-value expression rejects a missing or empty PROXY_URL. A file used for Compose interpolation does not automatically put every entry into a container; the explicit environment mapping performs that step. See Compose environment settings.

Move the settings into your application carefully

Environment variables are an instruction to cooperating HTTP clients. They do not intercept all container traffic. Check the networking library your application actually uses. A Node.js client, Java application, database connector and browser automation process can require different configuration even inside the same container.

For an authenticated HTTP proxy, a client may accept http://USERNAME:PASSWORD@HOST:PORT. Percent-encode reserved characters within each credential component once. Confirm support in that client, and use a separate proxy credential option when available. The authentication guide explains the input formats; the formatter helps separate provider export fields.

A credential stored in a container environment is visible to people and tools allowed to inspect its configuration. Keep authenticated environment files out of version control and avoid printing expanded Compose output. Docker Compose secrets can deliver a file to a service, but your application must read that file. Mounting a secret does not automatically create HTTP_PROXY or teach a client proxy authentication.

Use NO_PROXY for intentional direct connections such as internal service names. Matching rules vary between clients; test an internal destination and a public destination separately. Broad exceptions can silently send requests directly, while an incomplete list can accidentally send internal traffic to the external proxy.

A proxy on the host is another common trap: 127.0.0.1 inside a normal isolated container refers to that container. Use an address reachable from its network. If n8n is your application, continue with the n8n HTTP Request guide for its node-specific overrides.

Handle build-time proxy settings separately

For a non-secret endpoint, pass the predefined build variables:

docker build --build-arg HTTP_PROXY=http://proxy.example.com:3128 --build-arg HTTPS_PROXY=http://proxy.example.com:3128 .

Do not use a Dockerfile ENV instruction to bake an authenticated proxy URL into the image. Docker documents special handling for predefined proxy arguments, including exclusion from history and cache by default; referring to those arguments in the Dockerfile can remove that protection. Avoid echoing values in build logs. See build proxy arguments.

If a build needs an authenticated client configuration, prefer a BuildKit secret mount consumed directly by the package manager or HTTP client. Use its documented configuration-file format. A build secret is temporary, but a build command can still leak it by copying or printing its content. Review the resulting image and logs before distributing it.

Configure registry access at the daemon or Desktop

For standalone Docker Engine, the daemon proxy guide supports proxy configuration in daemon.json. Its keys use hyphens:

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

Merge the relevant keys into your existing configuration, validate it, and arrange the required daemon restart. A restart can affect running workloads. Docker Desktop ignores daemon proxy settings in this file; use its proxy settings interface. Rootless Engine and service-managed installations also have different environment locations.

Troubleshoot without mixing scopes

Symptom Likely next check
Image pull fails before the test runs Daemon/Desktop registry route and authentication.
407 inside the container Client proxy login and URL encoding.
Application keeps its original exit IP Client support, bypass rules and recreated container settings.
Connection refused Reachable host/port; avoid unintended container localhost.
Certificate error Container trust store and certificate chain.

Keep the error, operation and process together. A successful proxy test narrows the problem, while the error reference helps distinguish authentication from destination responses.

Frequently asked questions

Does Compose force all traffic through the proxy?

No. This example configures environment-aware HTTP clients. Other protocols require their own supported routing.

Should HTTPS_PROXY always start with https://?

No. It selects HTTPS destinations; the URL scheme describes the proxy connection. Use the provider’s actual protocol.

Will editing an environment file update a running service?

Recreate the service with the updated configuration, then test its actual requests. Editing the file alone does not change an existing process.

Why does curl work while docker pull fails?

Curl uses the container’s application settings; image pulls use the Docker daemon or Desktop backend. Check registry proxy settings separately from the container environment.

Compare BuyProxies dedicated proxy plans when your application needs a repeatable endpoint, then choose an authentication method compatible with its HTTP client. Browse developer examples for application-level setups.

Sources

Technical references reviewed October 2, 2026. See our editorial policy and testing methodology.

Scroll to Top