This page describes how to configure the Docker CLI to use proxies viaenvironment variables in containers.

This page doesn't describe how to configure proxies for Docker Desktop.For instructions, seeconfiguring Docker Desktop to use HTTP/HTTPS proxies.

If you're running Docker Engine without Docker Desktop, refer toConfigure the Docker daemon to use a proxyto learn how to configure a proxy server for the Docker daemon (dockerd) itself.

If your container needs to use an HTTP, HTTPS, or FTP proxy server, you canconfigure it in different ways:

• Configure the Docker client
• Set proxy using the CLI

Note

Unfortunately, there's no standard that defines how web clients should handle proxyenvironment variables, or the format for defining them.

If you're interested in the history of these variables, check out this blogpost on the subject, by the GitLab team:We need to talk: Can we standardize NO_PROXY?.

Configure the Docker client

You can add proxy configurations for the Docker client using a JSONconfiguration file, located in~/.docker/config.json.Builds and containers use the configuration specified in this file.

{"proxies":{"default":{"httpProxy":"http://proxy.example.com:3128","httpsProxy":"https://proxy.example.com:3129","noProxy":"*.test.example.com,.example.org,127.0.0.0/8"}}}

Warning

Proxy settings may contain sensitive information. For example, some proxy serversrequire authentication information to be included in their URL, or theiraddress may expose IP-addresses or hostnames of your company's environment.

Environment variables are stored as plain text in the container's configuration,and as such can be inspected through the remote API or committed to an imagewhen usingdocker commit.

The configuration becomes active after saving the file, you don't need torestart Docker. However, the configuration only applies to new containers andbuilds, and doesn't affect existing containers.

The following table describes the available configuration parameters.

These settings are used to configure proxy environment variables for containersonly, and not used as proxy settings for the Docker CLI or the Docker Engineitself.Refer to theenvironment variablesandconfigure the Docker daemon to use a proxy serversections for configuring proxy settings for the CLI and daemon.

Run containers with a proxy configuration

When you start a container, its proxy-related environment variables are setto reflect your proxy configuration in~/.docker/config.json.

For example, assuming a proxy configuration like the exampleshown in theearlier section, environmentvariables for containers that you run are set as follows:

$ docker run --rm alpine sh -c'env | grep -i  _PROXY'https_proxy=http://proxy.example.com:3129HTTPS_PROXY=http://proxy.example.com:3129http_proxy=http://proxy.example.com:3128HTTP_PROXY=http://proxy.example.com:3128no_proxy=*.test.example.com,.example.org,127.0.0.0/8NO_PROXY=*.test.example.com,.example.org,127.0.0.0/8

Build with a proxy configuration

When you invoke a build, proxy-related build arguments are pre-populatedautomatically, based on the proxy settings in your Docker client configurationfile.

Assuming a proxy configuration like the example shown in theearlier section, environmentare set as follows during builds:

$ docker build\  --no-cache \  --progress=plain \  - <<EOFFROM alpineRUN env | grep -i _PROXYEOF

#5[2/2] RUN env| grep -i _PROXY#5 0.100HTTPS_PROXY=https://proxy.example.com:3129#5 0.100no_proxy=*.test.example.com,.example.org,127.0.0.0/8#5 0.100NO_PROXY=*.test.example.com,.example.org,127.0.0.0/8#5 0.100https_proxy=https://proxy.example.com:3129#5 0.100http_proxy=http://proxy.example.com:3128#5 0.100HTTP_PROXY=http://proxy.example.com:3128#5 DONE 0.1s

Configure proxy settings per daemon

Thedefault key underproxies in~/.docker/config.json configures the proxysettings for all daemons that the client connects to.To configure the proxies for individual daemons,use the address of the daemon instead of thedefault key.

The following example configures both a default proxy config,and a no-proxy override for the Docker daemon on addresstcp://docker-daemon1.example.com:

{"proxies":{"default":{"httpProxy":"http://proxy.example.com:3128","httpsProxy":"https://proxy.example.com:3129","noProxy":"*.test.example.com,.example.org,127.0.0.0/8"},"tcp://docker-daemon1.example.com":{"noProxy":"*.internal.example.net"}}}

Set proxy using the CLI

Instead ofconfiguring the Docker client,you can specify proxy configurations on the command-line when you invoke thedocker build anddocker run commands.

Proxy configuration on the command-line uses the--build-arg flag for builds,and the--env flag for when you want to run containers with a proxy.

$ docker build --build-argHTTP_PROXY="http://proxy.example.com:3128" .$ docker run --envHTTP_PROXY="http://proxy.example.com:3128" redis

For a list of all the proxy-related build arguments that you can use with thedocker build command, seePredefined ARGs.These proxy values are only available in the build container.They're not included in the build output.

Proxy as environment variable for builds

Don't use theENV Dockerfile instruction to specify proxy settings for builds.Use build arguments instead.

Using environment variables for proxies embeds the configuration into the image.If the proxy is an internal proxy, it might not be accessible for containerscreated from that image.

Embedding proxy settings in images also poses a security risk, as the valuesmay include sensitive information.