Docker proxy settings for pulls, builds and containers

Short answers

Identify which operation is failing

Start with the command and the operation that failed. A registry pull failure happens before your application starts. A package download in a build step happens in the build environment. A request from the finished application happens in a running container. Changing an unrelated scope can leave the failing process untouched.

Docker’s client proxy documentation describes configuration that supplies proxy environment variables to new containers and builds. It explicitly distinguishes those values from settings for the CLI and daemon. The configuration does not retroactively update containers that are already running.

Check the application container without printing credentials

Confirm that the intended variables exist in the process that makes the request. Avoid printing the environment or a complete proxy URL: authenticated URLs can contain a password. This small Python presence check prints only whether a value is set. Run it in the relevant Python application environment; it does not contact a proxy or destination.

import os

for name in ("http_proxy", "HTTP_PROXY", "https_proxy", "HTTPS_PROXY", "NO_PROXY", "no_proxy"):
    state = "set" if os.environ.get(name) else "unset"
    print(f"{name}: {state}")

The original offline check runs the same script once with a synthetic https_proxy value and once without it. The first child reports set; the second reports unset. This demonstrates process-environment isolation only. It does not test Docker propagation, authentication, DNS, a build or a live gateway.

Next inspect the client library’s documented proxy behaviour. Some clients read environment variables, some need explicit configuration, and some let an explicit setting override the environment. Use the environment and client checklist rather than assuming that every containerised application treats the variables alike.

Keep build configuration separate from runtime configuration

Docker documents predefined proxy build arguments and client configuration for builds. Follow that mechanism for a build that needs a proxy. Do not add a permanent Dockerfile ENV instruction merely to make one download succeed; that can carry the configuration into images and containers where it is unwanted.

Build arguments are not a general secret-management guarantee. Referencing or exposing values in a Dockerfile, build output or another tool can change what is retained. Review the exact Dockerfile and the current build proxy instructions. Do not print values to prove they arrived.

For runtime requests, supply configuration through the application’s existing deployment and secret process. Docker warns that environment values are stored in container configuration and can be inspected. Keeping a password out of an image does not make every environment-based configuration confidential.

Change daemon settings only for a daemon problem

If registry access is the failing operation, read the daemon proxy instructions. They distinguish direct daemon configuration from its startup environment. Docker Desktop uses its own settings; the documented daemon.json proxy configuration is ignored by Desktop. Do not restart a shared daemon to troubleshoot an unrelated application request.

Identify whether you use Engine, Desktop, a remote daemon or a managed builder before applying platform instructions. A configuration file on your laptop does not establish which process runs a remote build. Coordinate any daemon change with the person responsible for that environment.

Check the endpoint and intended exclusions

The scheme in a proxy URL describes the connection to the proxy, not just the destination website. An HTTPS destination can use an HTTP proxy through CONNECT. Use the actual protocol, host and port from your purchased connection, and review proxy URL formatting if credentials contain special characters.

NO_PROXY can deliberately keep selected destinations off that route. Its interpretation is client-specific, so a hostname pattern that works in one tool may not behave identically in another. Check the intended exclusions and process configuration before changing the credential or buying another product.

Make a bounded check after configuration is understood

1. Record the failing operation, Docker environment and application client version.
2. Confirm the purchased product and copy its matching connection details privately.
3. Check configuration presence in the relevant process without logging values.
4. Use the client’s explicit documented settings and review intended host exclusions.
5. Run one permitted, time-bounded request and inspect both connection and application results.
6. If it fails, keep a redacted error and configuration context for support; do not share credentials.

Use shared proxy traffic when a GB allowance across shared pools fits the application, or review dedicated mobile ports when a reserved device term is required. This guide has no Docker runtime benchmark or live product test. Its offline presence fixture and official-source comparison establish the stated scope only.

What is not allowed

Use containerised connections for tasks you are authorised to perform and follow the destination rules and acceptable-use policy.

Read next