Configuring the gcloud CLI for use behind a proxy/firewall

If you are behind a corporate proxy or firewall, the Google Cloud CLI might notbe able to access the internet with its default settings.

Installing the gcloud CLI

The interactive gcloud CLI installers download components from theinternet as part of the installation process, which might not work correctly ifyou're behind a proxy or firewall.

For a simpler installation process when proxy configuration is necessary, useone of the self-containedversioned archivesto install the gcloud CLI. All previous versions of thegcloud CLI are also available to download from thedownloads archive.

Proxy configuration

Note: The gcloud CLI respects thehttp_proxy,https_proxy, andno_proxy environment variables set in your proxy configuration; these controlthe proxy server used for plain HTTP connections, the proxy server used forHTTPS connections (typically more relevant for most gcloud CLIcommands), and the domains not to proxy, respectively. Configure yourgcloudproxy settings only if you would like to use a different proxy. Ifgcloudproxy settings are set, they override existing proxy configuration; thisincludes ignoringno_proxy.Tip: If you see warnings or errors related to thehttps_proxy environmentvariable, it may be because you have specified e.g.https_proxy=https://...instead ofhttps_proxy=http://.... The latter is needed since thegcloud CLI only supports HTTP proxies. Earlier versions of thegcloud CLI silently ignored this difference and would alwaysattempt to contact the proxy via HTTP even if the proxy URL specified HTTPS.

After you have the gcloud CLI installed, proxy settings can beconfigured using gcloud CLI properties by runninggcloud config.For more information on what gcloud CLI properties are and how to usethem, refer to theproperties page.

To start, set the type of proxy you are using and the address and port on whichto reach it:

gcloudconfigsetproxy/type[PROXY_TYPE]gcloudconfigsetproxy/address[PROXY_IP_ADDRESS]gcloudconfigsetproxy/port[PROXY_PORT]
  • The gcloud CLI supports the following values forPROXY_TYPE:http,http_no_tunnel,socks4,socks5
  • PROXY_IP_ADDRESS is the hostname or IP address of where the proxy can bereached.
  • PROXY_PORT is the port the proxy is running on (e.g.8080).

For an authenticated proxy, you will need to set your proxy username andpassword usingproperties as follows:

gcloudconfigsetproxy/username[USERNAME]gcloudconfigsetproxy/password[PASSWORD]

Alternatively, to avoid having the proxy credentials recorded in any logs (suchas shell history or gcloud CLI logs) or in thegcloud CLI configuration file, you can set the properties usingenvironment variables, as shown in the following sample:

exportCLOUDSDK_PROXY_USERNAME[USERNAME]exportCLOUDSDK_PROXY_PASSWORD[PASSWORD]

The gcloud CLI won't store these values. This way, the credentialscan be stored in an encrypted file locally, or they can be stored in a securenetwork location and retrieved when necessary.

If you are behind a proxy and you receive SSL handshake errors, it's likelythat your proxy is a man-in-the-middle proxy which uses a custom CA. You needto set the following property to point to your custom CA file:

gcloudconfigsetcore/custom_ca_certs_file[PATH_TO_CUSTOM_CA]

For a full description of related properties, rungcloud topic configurationsorgcloud config setand look forproxy under the Available properties section.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-16 UTC.