Optimizing the Gradle Build System

Introduction: Build Bottlenecks and How to Break Through Them

For Android developers, especially teams working on large multi-module projects, Gradle build time is often one of the biggest pain points in daily development. Every wait for compilation and packaging consumes patience and productivity. Slow builds reduce iteration speed, interrupt coding flow, and can even become a serious obstacle as teams grow and project complexity increases.

Gradle itself is an extremely powerful and flexible build automation tool. It supports the build, test, and packaging process of modern Android applications. But that same flexibility, if not understood and used well, can also lead to bloated build scripts, complex configuration, and poor execution efficiency.

For senior Android experts and architects, deeply understanding how Gradle works, diagnosing build performance bottlenecks, and skillfully applying advanced optimization techniques to reduce build time are critical responsibilities. This directly affects the efficiency and well-being of the entire engineering team. It requires going beyond the basic syntax of build.gradle and going deeper into Gradle’s lifecycle, task graph, cache mechanism, parallel execution, and interaction with the Android Gradle Plugin, or AGP.

This article explores Gradle build system optimization in depth, mainly covering:

• Gradle core principles: lifecycle, task graph, and why inputs and outputs matter for optimization
• Performance bottleneck diagnosis: using --profile and --scan to locate time-consuming parts of the build
• Core optimization techniques: Gradle Daemon, parallel execution, configuration cache, build cache, incremental compilation, and annotation processing
• Dependency management optimization: the difference between api and implementation, plus version management strategies
• Multi-module project strategies: specific optimizations for modular architectures
• AGP optimization configuration: performance-related options provided by the Android Gradle Plugin
• KAPT and KSP: the performance key to annotation processing

1. Reviewing Gradle Core Principles from a Performance Perspective

To optimize Gradle, you first need to understand its basic workflow.

1. Build Lifecycle

A Gradle build goes through three main phases:

• Initialization

  • Gradle determines which projects participate in the build. For multi-module projects, this means parsing settings.gradle(.kts).
  • It creates the Settings object.
  • This phase is usually very fast unless settings.gradle contains complex logic.

• Configuration: an extremely important performance-sensitive phase

  • Execute scripts: Gradle executes all participating projects’ build.gradle(.kts) scripts in order.
  • Build the model: it creates and configures Project objects and all Task objects.
  • Build the task graph: it resolves dependencies among tasks, such as dependsOn and input/output relationships, builds a directed acyclic graph, or DAG, and determines which tasks need to run and in what order.
  • Performance traps: time spent in this phase directly affects the startup time of every build, even when no task ultimately needs to execute, such as in an UP-TO-DATE build. Avoid doing file IO, network requests, complex computation, and unnecessary object creation here. The goal of the configuration phase should be to define tasks and their relationships quickly and deterministically.

• Execution

  • Gradle executes the required tasks in order based on the task graph produced by configuration and the requested task, such as assembleDebug.
  • Optimization focuses on two things: making tasks execute faster through code optimization, and avoiding unnecessary task execution through incremental builds and caching.

Gradle build lifecycle diagram:

+-----------------+      +------------------------------------+      +-------------------------------------+
| Initialization  | ---> |           Configuration            | ---> |              Execution              |
|-----------------|      |------------------------------------|      |-------------------------------------|
| - Discover Projects |  | - Execute build.gradle(.kts) scripts|     | - Execute Tasks based on Task Graph |
| - Create Settings Obj| | - Create/Configure Project Objects  |     |   (Respects Dependencies)           |
+-----------------+      | - Create/Configure Task Objects     |     | - Skip UP-TO-DATE Tasks             |
                         | - Build Task Dependency Graph (DAG) |     | - Use Build Cache for Cacheable Tasks |
                         +------------------------------------+      +-------------------------------------+
                                      ^
                                      |
                                      +---- MAJOR BOTTLENECK AREA (Configuration Time)

2. Tasks

Tasks are Gradle’s units of work, such as compileKotlin, mergeDebugResources, lint, test, and assembleDebug.

• Task inputs and outputs: the foundation of Gradle optimization
  • Tasks declare their inputs, meaning factors that affect task results, and outputs, meaning produced results, through annotations such as @Input, @InputFile, @InputDirectory, @OutputFile, @OutputDirectory, and @Nested.
  • Purpose:
    • Incremental builds: Gradle compares the current build’s inputs with the previous build’s inputs. If inputs have not changed, the task’s outputs are considered UP-TO-DATE, and Gradle skips task execution. This requires the task author, or plugin developer, to correctly annotate all inputs and outputs.
    • Build Cache: Gradle calculates a Build Cache Key from the task inputs and the task implementation itself. If the current build’s cache key matches a previous build, possibly local or from another machine, Gradle can restore the task outputs directly from cache instead of executing the task. This also depends on accurate input and output declarations.

3. Plugins

Plugins such as AGP, the Kotlin Gradle Plugin, KAPT, and KSP extend Gradle by adding predefined tasks and configuration. Plugin behavior, especially the efficiency of their tasks and the accuracy of their input/output declarations, has a major impact on build performance.

4. Dependency Management

Gradle resolves and downloads dependencies during the configuration phase and, when downloads are needed, during the execution phase. Complex dependency graphs or slow networks can affect build time.

2. Diagnose First: Locate Build Performance Bottlenecks

Before optimizing, you must accurately find the bottleneck.

1. Gradle Profiler: --profile

• Usage: append --profile when running a Gradle task, such as ./gradlew assembleDebug --profile.
• Output: generates an HTML report under build/reports/profile/.
• Content:
  • Summary: total build time, configuration time, and task execution time.
  • Configuration: time spent by scripts and plugin application during configuration.
  • Task Execution: all executed tasks sorted by duration.
• Value: quickly determine whether the configuration phase is slow or specific tasks are slow, and identify the most time-consuming tasks.

2. Gradle Build Scan: --scan

• Usage: append --scan when running a Gradle task. On first use, Gradle asks you to accept the terms of service and enter an email address to receive the report link.
• Output: a detailed, interactive web report.
• Core value, far beyond --profile:
  • Performance overview: a clear breakdown of build time, including configuration, dependency download, and task execution.
  • Task details: execution time, result, such as SUCCESS, FROM_CACHE, UP-TO-DATE, SKIPPED, or FAILED, cacheability, inputs, and outputs for each task.
  • Timeline view: visualizes task execution order and parallelism.
  • Dependency analysis: detailed dependency resolution process and timing.
  • Network activity: dependency download duration and traffic.
  • Build cache analysis: cache hit rate, miss reasons, and avoidable build cache misses. Extremely useful for optimizing cache configuration.
  • Configuration phase analysis: detailed display of script execution, plugin application, and task creation time.
  • Test reports: integrated test results.
  • Environment and comparison: build environment information that can be compared with historical builds.
• A must-have for senior engineers: Build Scan is strongly recommended for deep, comprehensive build performance analysis and diagnosis.

3. Android Studio Build Analyzer

• Location: Build -> Build Analyzer.
• Function: automatically analyzes build output, identifies long-running tasks and potentially problematic plugins, such as non-incremental annotation processors, and provides optimization suggestions, such as enabling non-transitive R classes or migrating to KSP.
• Value: serves as a quick day-to-day inspection tool and provides clues for common issues.

3. Core Optimization Techniques: Speeding Up the Build

Mastering and applying the following techniques is key to improving Gradle build speed.

1. Gradle Daemon

• Principle: keep a Gradle process running in the background so every build does not need to restart the JVM and reload Gradle classes. This significantly reduces build startup time.
• Configuration: enabled by default. Ensure org.gradle.daemon=true is set in gradle.properties.
• Check: use ./gradlew --status to view Daemon status.

2. Parallel Execution

• Principle: in multi-module projects, if modules have no dependency relationship, Gradle can execute their tasks in parallel and fully use multi-core CPUs.
• Configuration: set org.gradle.parallel=true in gradle.properties.
• Prerequisite: project modules should be well separated with clear dependencies.

3. Configuration Cache: A Heavyweight Optimization

• Principle: cache the result of the configuration phase, including the task graph and task configuration. If build scripts and related inputs, such as gradle.properties, have not changed, later builds load the cached task graph directly and completely skip configuration script execution.
• Configuration: set org.gradle.configuration-cache=true in gradle.properties.
• Effect: greatly shortens build startup time for large multi-module projects, especially for UP-TO-DATE builds or builds after small changes.
• Challenges and practice:
  • Compatibility: all plugins and custom tasks used by the project must be compatible with the configuration cache. Incompatible tasks, such as tasks that access the Project object during execution, can invalidate the cache or cause build errors.
  • Migration: you may need to update plugin versions and modify custom tasks or build scripts to fix compatibility problems. Build Scan is the best way to diagnose configuration cache issues, because it clearly reports the incompatibility reason.
  • State management: Gradle needs to serialize the state required for task execution. Make sure task state is serializable.
  • Return on investment: for large projects, the payoff from spending time to enable configuration cache is usually huge.

4. Build Cache

• Principle: cache the outputs of cacheable tasks. When a task’s inputs, such as source code, dependencies, and parameters, are exactly the same as a previous build, Gradle restores outputs directly from cache and skips task execution.
• Configuration: set org.gradle.caching=true in gradle.properties. Local caching is enabled by default in many setups.
• Local cache: stored under the user directory, such as ~/.gradle/caches/build-cache-1. It speeds up repeated local builds and branch switching.
• Remote Build Cache: the key to team collaboration:
  • Mechanism: upload build cache entries to shared remote storage, such as an internal HTTP/S3 server or Gradle Enterprise Cache Node. Team members and CI servers can share cached results.
  • Configuration: configure the buildCache block in settings.gradle(.kts) with the remote cache type, URL, credentials, and related options.
  • Effect: greatly improves the overall build speed of the team. Developers can reuse cache generated by CI or other teammates.
• Key point: tasks must correctly declare inputs and outputs to be cacheable. Build Scan can analyze cache hit rate and miss reasons.

5. Incremental Compilation

• Java: Javac itself supports incremental compilation, and Gradle uses it by default.
• Kotlin: the Kotlin Gradle Plugin also supports incremental compilation. Make sure you use a recent version. Complex type inference or cross-module dependencies can sometimes break incrementality, so pay attention to it.

6. Incremental Annotation Processing: A Common Pain Point

KAPT:

• Problem: KAPT generates Java stubs so Java annotation processors can process Kotlin code. This process usually does not support precise incremental processing and can disable Java and Kotlin incremental compilation for that module. Even when KAPT is used, the module may be fully recompiled on every build.
• Impact: it severely slows builds, especially in modules with multiple KAPT dependencies.

KSP, or Kotlin Symbol Processing:

• Advantages: officially introduced by Google as an alternative to KAPT. It is an API that works directly on the Kotlin compiler frontend and understands Kotlin code structure.
  • Faster: usually much faster than KAPT.
  • Supports incrementality: if the annotation processor itself supports KSP’s incremental mode, KSP can provide real incremental annotation processing.
  • Does not break Kotlin/Java incremental compilation: running KSP does not affect the module’s own incremental compilation.
• Migration: strongly consider migrating KAPT dependencies in the project to KSP. Check whether the libraries you use, such as Dagger/Hilt, Room, Moshi, and Glide, provide KSP support.
• Effect: migrating to KSP usually brings significant build speed improvements.

4. Optimizing Dependency Management

The number of dependencies and how they are resolved also affect build performance.

1. implementation vs api: keep using implementation unless api is absolutely necessary, for example when a module’s public API exposes types from a dependency. Reducing unnecessary transitive dependencies can speed up compilation and improve cache hit rates.

2. Pin dependency versions: avoid dynamic versions, such as +, latest.release, and version ranges. Use explicit versions such as 1.2.3. Dynamic versions force Gradle to check the network for the latest version on every build, or according to a policy, breaking build determinism and cache effectiveness. They can also introduce compatibility problems.

3. Version Catalogs: use a libs.versions.toml file to centrally manage all dependency coordinates and versions. This improves maintainability and consistency and integrates well with IDEs.

4. Dependency analysis: regularly review project dependencies and remove libraries that are no longer used. Use ./gradlew :app:dependencies to inspect the dependency tree and analyze version conflicts or unnecessary transitive dependencies.

5. Multi-Module Project Strategies

Modularization itself solves monolithic project problems, but it also needs specific optimizations.

1. Parallel execution: parallel=true is more effective in multi-module projects.

2. Build Cache, especially Remote Build Cache: a core source of benefit. It can cache build outputs for unchanged modules.

3. Configuration Cache: projects with many modules can spend a long time in the configuration phase, and configuration cache can have a major effect.

4. Convention Plugins: create custom plugins in buildSrc or an independent includedBuild to centralize common configuration across modules, such as AGP version, SDK version, common dependencies, and plugin application. This greatly simplifies each module’s build.gradle file and improves consistency and maintainability.

5. Pure Java/Kotlin modules: extract logic that does not depend on the Android framework, such as the Domain layer, utility classes, and data models, into java-library or kotlin("jvm") modules. They compile much faster than com.android.library modules.

6. Android Gradle Plugin Optimization Configuration

AGP itself also provides some optimization options.

1. Keep AGP updated: Google continuously optimizes performance in AGP.

2. Non-transitive R classes, android.nonTransitiveRClass=true:

   • Principle: by default, a library module’s R class contains resource IDs from all of its transitive dependencies. After enabling this option, a library module’s R class contains only the resource IDs it defines itself. An app module or another library module must directly depend on the library that contains the resources it wants to access.
   • Advantages: this strengthens resource isolation between modules. Changing resources in one library usually no longer requires recompiling other libraries that depend on it, unless the dependency is exposed through api. This significantly improves resource-related build incrementality.
   • Practice: strongly recommended. You may need to adjust code to ensure modules directly depend on the modules that contain the required resources.

3. Disable PNG Crunching for Debug builds: set crunchPngs false in buildTypes.debug. Older AGP versions used aaptOptions.cruncherEnabled = false. This can speed up resource processing for debug builds. Release builds should keep it enabled to optimize APK size.

4. Optimize BuildConfig and ResValue: if BuildConfig or resValue is not used, disable them in buildFeatures, such as buildConfig = false and resValues = false, to reduce code generation.

7. Plugin and Build Logic Considerations

• Inputs and outputs for custom tasks and plugins: if you write custom Gradle Tasks or Plugins, you must precisely declare all input and output properties to ensure incremental builds and the build cache work properly. Use annotations such as @Input, @InputFile, @InputFiles, @InputDirectory, @OutputFile, @OutputDirectory, and @Nested.

• Configuration phase vs execution phase: clearly distinguish which logic should run during configuration, meaning task and dependency definition, and which logic should run during execution, meaning the actual task work. Avoid doing too much work during configuration.

• Configuration cache compatibility: when writing tasks and plugins, follow configuration cache best practices, such as using the Provider API to defer input value calculation and avoiding access to the Project object during execution.

8. Conclusion: Continuous Optimization, Pursuing Maximum Efficiency

Gradle build optimization is a systematic engineering field that requires continuous investment. For large Android projects, it is no longer a “nice to have”; it is a lifeline for protecting team development efficiency and project health. Significant performance gains usually come from a deep understanding of Gradle’s core mechanisms and the bold adoption and adaptation of key features, especially Configuration Cache, Build Cache, particularly Remote Cache, parallel execution, and migration from KAPT to KSP.

Merely applying configuration switches is not enough. We also need a methodology for using --profile and --scan to analyze performance bottlenecks, interpret reports, and locate problems. At the same time, we need best practices in project structure, such as modularization; dependency management, such as implementation and Version Catalogs; and build logic encapsulation, such as Convention Plugins.

There is no silver bullet for Gradle optimization. It must be continuously iterated based on each project’s specific situation and data analysis. A fast, stable, and reliable build system is the solid foundation of a high-performing engineering team. Control over the Gradle build system is an important measure of a senior Android engineer’s or architect’s capability.