Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 36 ยท Performance and Migration

Gradle Daemon, Parallel Builds and the Configuration Cache

Speed up Gradle builds: the daemon, gradle.properties JVM settings, parallel execution, the configuration cache, build scans and profiling, and a checklist for slow builds.

A slow build costs every developer minutes each day. Gradle has several speed features that stack on top of incremental builds and the build cache: a long-lived daemon process, parallel project execution, and the configuration cache, which skips the configuration phase altogether.

This lesson explains each feature, the settings that control it, how to measure where the time goes, and a practical checklist.

Gradle cannot run on this site. Commands and properties are shown read-only. Java stand-ins demonstrate parallel scheduling and caching of an expensive setup step on Piston.

The three build phases

Every Gradle run has three phases:

flowchart LR
    A["Initialization<br/>read settings, find projects"] --> B["Configuration<br/>evaluate build scripts, build task graph"]
    B --> C["Execution<br/>run the selected tasks"]

Faster builds shorten one or more phases.

  • Incremental builds and the build cache shorten execution.
  • The daemon keeps JIT-compiled Gradle code in memory, helping all phases.
  • The configuration cache skips initialization and configuration when nothing relevant changed.
  • Parallelism shortens execution (and optionally configuration).

The Gradle daemon

Starting a JVM and loading Gradle takes seconds. The daemon is a background JVM that stays alive between builds, so the next ./gradlew command starts almost instantly, with warm caches. It is on by default.

TEXT
./gradlew --status            # list running daemons
./gradlew --stop              # stop all daemons
./gradlew build --no-daemon   # one-off, no daemon (CI containers sometimes)

Daemons expire after a few hours idle. Different JVM settings or Gradle versions use different daemons, so many projects mean many daemons; keep an eye on RAM.

gradle.properties: the main tuning file

TEXT
# JVM for the Gradle daemon itself
org.gradle.jvmargs=-Xmx3g -XX:MaxMetaspaceSize=768m -Dfile.encoding=UTF-8

org.gradle.parallel=true
org.gradle.caching=true
org.gradle.configuration-cache=true
org.gradle.daemon=true

Notes:

  • org.gradle.jvmargs configures the daemon JVM. Tests and compilers fork their own JVMs, configured on their tasks (maxHeapSize, kotlin.daemon.jvmargs).
  • Put project-wide properties in the repository's gradle.properties, personal ones in ~/.gradle/gradle.properties.
  • Too small a heap causes constant garbage collection; too large wastes memory and may hit container limits. Start at 2 to 4 GB for medium projects.

Parallel execution

Gradle can run tasks of different projects at the same time when org.gradle.parallel=true. Within one project, tasks are serialized unless you use the Worker API or a plugin that parallelizes internally (the Java compiler has no parallelism of its own, but the Kotlin compiler and tests with maxParallelForks do).

Parallelism needs:

  • independent projects (a wide dependency graph, see project dependencies),
  • tasks that do not write into other projects' directories,
  • enough CPU cores. The setting org.gradle.workers.max limits the number of workers; the default is the number of cores.
Java Stand-in: sequential vs parallel task execution (not Gradle)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The stand-in prints booleans instead of timings, so the output is stable on any machine. In real Gradle, the dependent project still waits for its upstream projects; only independent ones overlap.

The configuration cache

Gradle must evaluate all build scripts to know the task graph. In a big build this can take many seconds. The configuration cache saves the task graph after the first run and reuses it when the build scripts, settings, relevant files and inputs are unchanged:

TEXT
./gradlew build --configuration-cache
TEXT
Configuration cache entry stored.
...
Reusing configuration cache.

To work with it, build logic must follow rules: tasks cannot reference the Project object during execution, must not read environment variables, system properties or files at configuration time without going through providers, and must have serializable state. Violations produce a report (build/reports/configuration-cache/...) listing each problem with a location.

Typical fixes:

Kotlin
// Bad: reads project at execution time
tasks.register("bad") { doLast { println(project.name) } }

// Good: capture the value during configuration
tasks.register("good") {
    val projectName = project.name
    doLast { println(projectName) }
}

// Reading an environment variable the right way
val token = providers.environmentVariable("TOKEN")

Many core and popular plugins are already compatible. If one is not, you can switch to org.gradle.configuration-cache.problems=warn while migrating.

Java Stand-in: caching an expensive configuration step

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Measuring: profile and build scans

Guessing rarely finds the bottleneck. Measure:

  • ./gradlew build --profile writes an HTML report to build/reports/profile/ with time spent in configuration and per task.
  • ./gradlew build --scan publishes a build scan (a web report with a timeline, dependency resolution times, cache hits and why tasks ran) after you accept the terms of service. Be careful about what data it shares on private projects; a self-hosted Develocity server keeps data in-house.
  • --info and --debug show reasons for executing tasks.
  • ./gradlew help --task <name> explains a task.

A checklist for slow builds

  1. Update Gradle and plugins; each release brings performance work.
  2. Enable parallel, build cache and, if plugins allow, the configuration cache.
  3. Give the daemon enough heap and avoid swapping.
  4. Profile; fix the worst offender first (often one huge compile or test task).
  5. Split giant projects into modules that can be compiled and cached independently.
  6. Avoid allprojects {}, dynamic versions (1.+) and resolving configurations during configuration.
  7. Use implementation rather than api to reduce recompilation.
  8. Keep generated or downloaded files out of task inputs unless needed.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which Gradle feature keeps a JVM alive between builds so later builds start faster?

    The daemon is a long-lived background process that keeps Gradle loaded and warmed up.
  2. 2. What does org.gradle.parallel=true let Gradle do?

    Parallel execution schedules tasks of projects that do not depend on each other at the same time.
  3. 3. What does the configuration cache skip?

    It stores the task graph so the configuration phase can be reused.
  4. 4. How do you find where build time goes?

    Profile reports and build scans show time per phase and task, so you can fix real bottlenecks.

Summary

  • Gradle builds have initialization, configuration and execution phases; each speed feature targets some of them.
  • The daemon removes startup cost; tune it with org.gradle.jvmargs.
  • Parallel execution overlaps independent projects; wide dependency graphs benefit most.
  • The configuration cache reuses the task graph but requires build logic that avoids the Project at execution time.
  • Measure with --profile and build scans before optimizing.

Next: Migrating from Maven and Ant to Gradle