Gradle Optimization: Speeding Up Android App Builds

Introduction / Why This Matters

Gradle is the build system for Android applications, and its configuration directly impacts development speed. By default, settings are often conservative and don't utilize the full potential of modern hardware. Incorrect configuration can turn project builds into a "bottleneck," consuming precious minutes (and sometimes hours) on every iteration.

In this guide, you will check and optimize key Gradle parameters, which on average speeds up Debug builds by 30-50% and full builds by 2-3 times. We will focus on parameters that are safe for most projects and compatible with the latest versions of the Android Gradle Plugin (AGP).

Requirements / Preparation

Before starting, ensure that:

1. You have Android Studio Flamingo (2022.2.1) or newer installed.
2. Your project uses Android Gradle Plugin (AGP) 8.0+ and Gradle 8.0+. You can verify this in the files:
   • gradle/wrapper/gradle-wrapper.properties (check distributionUrl)
   • Project-level build.gradle in the classpath 'com.android.tools.build:gradle:...' block
3. You have write permissions for the root folder of the Android project.
4. The project builds successfully in its current configuration (to have a baseline for comparison).

Step 1: Find or Create gradle.properties

The gradle.properties file is the central place for global Gradle settings. It must be located in the root of your project (where settings.gradle or settings.gradle.kts resides).

• If the file already exists — open it.
• If it does not exist — create a new text file named gradle.properties in the project root.

There is also a user-specific file ~/.gradle/gradle.properties (in the home directory). Settings from this file apply to all projects. We will edit the file within the project so that changes are local and version-controlled.

Step 2: Add Basic Performance Parameters

Add the following lines to gradle.properties. These enable key acceleration mechanisms:

# Enables the Gradle Daemon - a background process that speeds up build startup
org.gradle.daemon=true

# Enables parallel execution of modules (not to be confused with parallel tasks within a module)
org.gradle.parallel=true

# Enables build cache caching (caches intermediate task results)
org.gradle.caching=true

What these parameters do:

• daemon: The daemon stays in memory after the build, eliminating the JVM "cold start" on the next run.
• parallel: Allows Gradle to build different project modules simultaneously (if modules do not depend on each other).
• caching: Saves task execution results between builds. If inputs (sources, dependencies) haven't changed, the task isn't re-executed.

Step 3: Configure JVM Arguments for Gradle

This is the most important block for performance. Lack of memory is a common cause of slow builds and OutOfMemoryError. Add:

# Maximum heap memory size for the Gradle daemon.
# Set it to 25-50% of available RAM, but no more than ~4-6 GB.
# Example for 16 GB RAM: -Xmx4g
org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=1024m -Dfile.encoding=UTF-8

# Recommended garbage collector for long-lived processes (like the Daemon)
org.gradle.jvmargs=-XX:+UseParallelGC -XX:MaxGCPauseMillis=200

How to calculate -Xmx:

1. Determine how much RAM is typically free while Android Studio is running.
2. Allocate no more than 50% of that value to Gradle. For example, if you have 16 GB and the IDE + emulator use 8 GB, 4-6 GB remains for Gradle.
3. A value that is too high (e.g., -Xmx8g on a machine with 8 GB) will cause swapping and slow down the system.

Combined example for org.gradle.jvmargs:

org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=1024m -XX:+UseParallelGC -XX:MaxGCPauseMillis=200 -Dfile.encoding=UTF-8

Step 4: Enable Configuration on Demand and Caching for AGP

For Android projects, there are specific parameters that significantly speed up incremental builds:

# Enables "configuration on demand" for AGP.
# Allows building only the modules required for the current task.
android.experimental.enableNewResourceShrinker=true
android.experimental.enableSourceSetPathsMap=true

# Enables caching of resources and manifests between builds.
android.advancedApkSigning=true
android.aptCache=true

Note: The android.experimental.enableNewResourceShrinker parameter has been stable since AGP 7.0+. Other experimental flags may change. Check the official documentation for the latest status with your AGP version.

Step 5: Configure Parallelism for Tasks Within a Module

The org.gradle.parallel parameter manages parallelism between modules. For parallelism within a module (e.g., compiling Java/Kotlin files, processing resources), a different property is used:

# Sets the maximum number of worker processes for tasks within a module.
# Optimal value: number of physical CPU cores (not hyper-threads).
# Automatic setting: org.gradle.workers.max=auto
org.gradle.workers.max=4

How to determine the value: Run nproc (Linux/macOS) or check Task Manager (Windows) for the number of physical cores. For a 4-core CPU, set 4; for an 8-core CPU, set 6 or 8. A value that is too high (e.g., org.gradle.workers.max=16 on a 4-core machine) will cause resource contention and slow down the build.

Step 6: Apply Changes and Verify the Result

1. Save the gradle.properties file.
2. Stop all running Gradle daemons. In the terminal, execute:

   ./gradlew --stop
   

3. Clean the project to start a "fresh" build with the new settings (this is important for the first measurement):

   ./gradlew clean
   

4. Build the project and enable build-time logging:

   ./gradlew assembleDebug --profile
   

   
   The --profile flag generates a report at build/reports/profile/<timestamp>/profile.html. Open it in a browser.
5. Analyze the report:
   • In the "Tasks" tab, you will see the execution time for each task. Look for long-running tasks (:app:mergeDebugResources, :app:compileDebugKotlin).
   • In the "Build metrics" tab, check the values for Daemon (should be true) and Configuration cache (if enabled).
   • Compare the total build time (BUILD SUCCESSFUL in the console) with the time before the changes.

Verifying the Result

Successful optimization manifests as:

1. Reduced time for the "first" build (after clean). Expected effect: 10-30% faster due to org.gradle.jvmargs and org.gradle.workers.max.
2. Significant acceleration of "incremental" builds (without clean). Expected effect: 2-5 times faster due to org.gradle.caching, org.gradle.daemon, and android.* flags.
3. Smooth operation in Android Studio without hiccups during auto-build (Build → Make Project). This indicates adequate org.gradle.jvmargs settings.
4. Absence of errors like GC overhead limit exceeded or Java heap space in the Gradle console.

Potential Issues

Issue: Builds became slower or fail with memory errors

Solution: The org.gradle.jvmargs values are likely too aggressive for your RAM size. Decrease -Xmx (e.g., from 4096m to 2048m). Also, check if android.experimental.* flags conflict with your AGP version. Try commenting them out.

Issue: Gradle daemon fails to start or constantly restarts

Solution: Ensure org.gradle.daemon=true. Check for conflicting settings in other sources (e.g., in ~/.gradle/gradle.properties). Run ./gradlew --status to see daemon status.

Issue: Parallel build breaks the project (inconsistent artifacts)

Solution: Rarely, this can happen with incorrect dependencies or side-effect tasks in build.gradle. Temporarily disable org.gradle.parallel and build the project to isolate the problematic module. The issue is often in a module's build.gradle that implicitly depends on another module's artifacts.

Issue: CI/CD fails after enabling caching

Solution: In a clean CI environment, the Gradle cache is disabled by default. org.gradle.caching settings may require pre-warming the cache. For CI, it's common to use a separate gradle.properties.ci file or pass parameters via the command line, disabling the cache: -Dorg.gradle.caching=false.