← Back to Blog

How to Configure Proxy in Android Studio and Gradle: gradle.properties and SDK Manager

We discuss how to correctly configure the proxy in gradle.properties, set up the SDK Manager and Android Studio, and resolve the most common Gradle synchronization errors.

📅November 13, 2026

If Android Studio is "hanging" during the Gradle sync, the SDK Manager is not loading components, and dependencies from Maven Central are not downloading — in 80% of cases, the problem lies not in the code but in the network environment. A corporate firewall, VPN, IP repository blocking, or simply a lack of direct internet access can all be resolved with the correct proxy configuration at three levels: IDE, Gradle, and SDK Manager. Let’s discuss how to set up the proxy correctly and avoid unnecessary sync errors.

Why Android Developers Need a Proxy

Proxies are most commonly used in conjunction with Android Studio in several scenarios. The first is a corporate network where direct internet access is restricted, and all traffic, including requests to google(), mavenCentral(), and dl.google.com, must go through the company's proxy server. The second is bypassing regional restrictions: some SDK components, Google Play Services APIs, or third-party repositories are not directly accessible from certain countries, forcing developers to route traffic through an IP from another geolocation.

The third scenario involves testing geo-dependent functionality of the application. If the application displays different content, prices, or advertisements based on the user's country, QA engineers and developers need to emulate requests from the required region during the build and debugging stages, without waiting for the release. The fourth scenario is working with CI/CD runners that are physically located in data centers with restricted access to certain services, making the proxy the only way to "reach" the required repository or API.

In all these cases, the logic is the same: Gradle, SDK Manager, and the IDE itself must know the address, port, and, if necessary, the credentials of the proxy server; otherwise, the project sync will fail with timeouts or connection errors.

Which Type of Proxy to Choose for Development

For development and testing, stability of the connection and a low percentage of interruptions during long downloads (for example, Android SDK Platform Tools can be hundreds of megabytes) are more important than anonymity. Below is a comparison of proxy types relevant to Android developers' tasks.

Proxy Type When to Use Features
Datacenter Proxies Downloading SDK, Gradle sync, CI/CD High speed, low cost, stable for large downloads
Residential Proxies Testing geo-dependent APIs and content IPs of real users, less frequently blocked by services
Mobile Proxies Testing mobile APIs and push notifications from a specific country IPs of mobile operators, closely resembling real mobile traffic

For clean Gradle synchronization and downloading dependencies, it is more reasonable to use datacenter proxies — they provide stable high speed without unnecessary delays. If the task is to check how the application's backend responds to a user from another country, residential or mobile IPs are more suitable.

Configuring Proxy in gradle.properties

The gradle.properties file is the main place where Gradle looks for proxy settings for HTTP and HTTPS connections. The file can be located in the project root (only applies to that project) or in the global directory ~/.gradle/gradle.properties (applies to all projects on the machine). For consistent proxy usage, the second option is recommended.

# ~/.gradle/gradle.properties

systemProp.http.proxyHost=proxy.example.com
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.example.com
systemProp.https.proxyPort=8080

# optional — exceptions that go directly, bypassing the proxy
systemProp.http.nonProxyHosts=localhost|127.0.0.1|*.internal.corp

After saving the file, be sure to click File → Sync Project with Gradle Files or the "elephant" icon on the toolbar. If the IDE does not pick up the changes automatically, restart Android Studio — sometimes the proxy settings cache persists until the Gradle Daemon process is restarted.

An important nuance: the parameters systemProp.* apply specifically at the JVM level in which Gradle runs, so they affect not only the downloading of dependencies but also any network requests within build scripts (for example, if you have a custom Gradle task that calls an external API).

Configuring Proxy in Android Studio

In addition to Gradle, the IDE has its own network settings — these are needed for plugin operations, IDE updates, license checks, and some features like suggestions from Google. You can access them via File → Settings → Appearance & Behavior → System Settings → HTTP Proxy (on macOS — Android Studio → Preferences).

In the opened window, select Manual proxy configuration, specify the host and port, and if necessary, check Proxy authentication and enter the username and password. There is also a convenient Check connection button — enter a test URL (for example, https://dl.google.com) and click it to ensure the connection is working correctly before starting a full project sync.

It’s important to understand the difference

The HTTP Proxy settings in Settings affect the IDE itself (plugins, updates), while the parameters in gradle.properties affect the Gradle build process. These are two independent mechanisms, and for full functionality behind a proxy, both usually need to be configured.

Proxy for SDK Manager

The SDK Manager is a separate component that downloads Android platforms, build-tools, emulators, and system images. It has its own proxy configuration, which is historically set through the same system settings as the IDE, but when working with the standalone sdkmanager (CLI utility from the command line), the parameters need to be passed explicitly via JVM flags.

sdkmanager --proxy=http \
  --proxy_host=proxy.example.com \
  --proxy_port=8080 \
  --list

If sdkmanager is launched via a script, you can specify the proxy directly in the JAVA_OPTS environment variable, which the executable file reads:

export JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"

A common mistake is to configure the proxy in Android Studio but forget about standalone utilities like sdkmanager or avdmanager, which run as a separate Java process and do not automatically inherit the IDE settings.

Proxy for gradlew and Environment Variables

If you are building the project from the terminal using the wrapper ./gradlew, bypassing the IDE (for example, in CI/CD or simply out of habit), you can pass the proxy directly in the command without changing gradle.properties:

./gradlew build \
  -Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
  -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080

For consistent use, it is more convenient to set the GRADLE_OPTS environment variable in the shell profile (.bashrc, .zshrc for Linux/macOS or environment variables for Windows):

export GRADLE_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"

This is especially useful in CI runners like GitHub Actions, GitLab CI, or Jenkins, where environment variables are set once at the job level and automatically picked up by all subsequent build steps, without the need to edit project files.

Common Sync Errors and Their Solutions

Let’s discuss the most common errors developers encounter when configuring proxies and the specific steps to resolve them.

Error Cause Solution
Connection timed out Proxy not specified or unavailable Check host/port in gradle.properties, test proxy availability via curl
407 Proxy Authentication Required Username/password not provided Add systemProp.http.proxyUser and systemProp.http.proxyPassword
Unable to resolve host DNS resolution is not going through the proxy Use socksProxyHost instead of http for SOCKS5 with remote DNS
Could not GET 'https://dl.google.com/...' Gradle settings are specified, but not in the IDE (or vice versa) Synchronize settings in both places: Settings → HTTP Proxy and gradle.properties
SSL handshake failed Proxy intercepts SSL (corporate MITM) Import the proxy's root certificate into the cacerts of your JDK

If the error occurs specifically when downloading certain Maven artifacts (for example, androidx.* libraries), it is helpful to temporarily enable Gradle's verbose logging with the command ./gradlew build --info — the output will show which specific request is causing the connection drop and what response code the server returns.

Authenticated Proxy: Username and Password

If the proxy requires authentication (which is standard for paid proxy services and corporate gateways), you need to add two more lines in gradle.properties:

systemProp.http.proxyUser=myuser
systemProp.http.proxyPassword=mypassword
systemProp.https.proxyUser=myuser
systemProp.https.proxyPassword=mypassword

Storing the proxy password in plain text in the project gradle.properties, which goes into version control, is a bad practice. Use a global file in the user's home directory that is not committed to Git, or pass the password via environment variables during the CI/CD stage to prevent secrets from leaking into the repository.

For scenarios requiring IP rotation (for example, testing API limits from different addresses), it is more convenient to use proxy services with a ready pool of addresses and a single login — then the rotation is configured on the provider's side, and in gradle.properties, only the session port changes without rewriting the entire project configuration.

Diagnostic Checklist

If synchronization still fails after all settings, go through the following points in order:

  • Check the availability of the proxy directly with the command curl -x http://proxy.example.com:8080 https://dl.google.com
  • Ensure that the settings are specified in both Settings → HTTP Proxy and gradle.properties simultaneously
  • Clear the Gradle cache: ./gradlew --stop and delete the .gradle/caches folder
  • Check that there are no extra spaces or quotes around the values of host/port in the file
  • If using SOCKS5 — specify socksProxyHost/socksProxyPort instead of http.proxyHost
  • For corporate MITM proxies, import the certificate into the JDK's trusted certificate store (keytool -import)
  • Restart Android Studio and the Gradle Daemon after any changes to the properties files

Conclusion

Configuring a proxy in Android development involves working at three levels: system settings in Android Studio for the IDE itself, systemProp parameters in gradle.properties for the build process, and a separate configuration for standalone utilities like sdkmanager. Most sync errors arise from one of the levels being configured while another is forgotten, or from a lack of authentication on a proxy that requires it.

If the task is simply to reliably download dependencies and SDK components through a working proxy, datacenter proxies are excellent for this purpose — they are fast and do not create unnecessary delays during large downloads. However, if you need to test how the application behaves for a user from a specific country or from a mobile operator, consider residential proxies or mobile IPs — they provide a more realistic picture of service behavior in different regions.