A mental model for Gradle

Gradle is not slow because it is badly written. It is slow because a build is a program that has to answer hard questions — which versions win, which tasks are up to date, which variants exist — and because most build scripts accidentally make it answer those questions more often than necessary.

TL;DR#

• A Gradle build has three phases: initialisation (which projects exist), configuration (which tasks exist), execution (run the tasks).
• The configuration phase is where most slowness lives. It runs before any task, for every build.
• The task graph connects tasks by inputs and outputs. Up-to-date checks and the build cache both depend on those declarations being honest.
• The configuration cache skips the configuration phase entirely when its inputs have not changed.
• Variants are the cross product of build types and flavours. They multiply tasks, not builds.
• If two modules have the same code, Gradle still configures both. Modularisation is not free at configuration time.

Mental model#

Think of Gradle as a theatre company preparing a performance.

Initialisation is the company deciding which theatres it is performing in tonight — one project, or three with a shared parent. Configuration is the rehearsal: every actor reads the whole play, every prop is checked, every scene is scheduled. It happens even if the play is a one-minute commercial. Execution is the performance itself: only the scenes that are needed run, and only if something changed since last time.

The build cache is a warehouse of previously performed scenes. If a scene's script and props are identical to a recorded performance, the recording is reused without rehearsing it.

Where the analogy breaks#

A theatre company rehearses once and performs many times. Gradle reconfigures on every invocation unless you enable the configuration cache — and that is the single biggest source of surprise about build times. A build can take 40 seconds and produce no output because it spent all 40 in configuration, and nothing in the output says so unless you ask.

The big picture#

Click any cell. The four source sets are shown in merge order, and that order is the whole variant system: a free flavour resource overrides a main resource, and a freeDebug resource overrides both.

Deep dive#

The three phases#

Initialisation reads settings.gradle.kts, decides which projects are in the build, and creates a Project object for each. Nothing about Android exists yet.

Configuration runs every project's build script. This is where android { ... } blocks execute, where dependencies are declared, and where tasks are registered. It runs for tasks you did not ask for, because Gradle cannot know what to run until every project has said what it can do.

Execution runs the requested tasks, in dependency order, skipping any whose inputs and outputs are unchanged. The three-phase model is documented in Gradle's own build lifecycle guide.¹

# Configuration only, no execution
./gradlew :app:tasks
 
# Execution, with timing per phase
./gradlew :app:assembleDebug --profile

The --profile flag writes an HTML report that separates configuration time from execution time. That report is the first thing to look at when a build "feels slow": if configuration dominates, no amount of --parallel will help.

Why configuration is expensive#

Every android { } block does real work: it resolves the SDK, reads the manifest, discovers variants and registers hundreds of tasks. Multiply by every module, and a fifty-module project can spend a minute before it compiles anything.

The classic anti-pattern is work in the configuration phase that should happen in a task:

// Bad: runs on every configuration, for every build
val versionFile = file("version.txt")
val version = versionFile.readText().trim()
 
android {
    defaultConfig { versionName = version }
}

This reads a file during configuration. It is not cacheable, it is not tracked, and it runs even for ./gradlew tasks. The fix is to make it an input to a task, or to accept the cost and declare it — but the first step is to notice it.

Inputs, outputs, and up-to-date checks#

A task is skipped when its declared inputs are unchanged and its declared outputs still exist. That is all. There is no magic.¹

abstract class GenerateBuildInfo : DefaultTask() {
    @get:Input abstract val versionName: Property<String>
    @get:Input abstract val gitSha: Property<String>
    @get:OutputFile abstract val output: RegularFileProperty
 
    @TaskAction
    fun generate() {
        output.get().asFile.writeText(
            """object BuildInfo {
                const val VERSION = "${versionName.get()}"
                const val SHA = "${gitSha.get()}"
            }"""
        )
    }
}

Declaring gitSha as an @Input means a new commit invalidates the task. Forgetting to declare it means the task is considered up to date and the app ships with a stale SHA — a bug that is very hard to connect to its cause.

The build cache and the configuration cache#

They sound similar and solve different problems.

A remote build cache is what makes CI fast: one machine compiles a module, every subsequent build on any machine with the same inputs restores the output.² The configuration cache is what makes local incremental builds feel instant.

Both require the build to be honest about inputs. That is why enabling either one on an old project often surfaces latent bugs — which is annoying, and also the point.

Variants multiply tasks, not processes#

The variant matrix above has nine cells. Gradle does not run nine separate builds; it builds one graph with shared nodes. compileReleaseKotlin is shared by every release variant that has the same sources; mergeFreeDebugResources is unique to one.

This is also why flavour count has a superlinear cost. Each flavour adds source sets, and each variant adds a manifest merge and a resource merge. Two flavours and two build types is four variants and manageable. Five flavours and three build types is fifteen, and every one of them configures.

Why modularisation is not a free lunch#

A common belief: "split the app into modules and builds get faster." The execution phase does get better — unchanged modules are not recompiled. But the configuration phase gets worse, because every module has a build script that must run.

The net effect depends on the project. For a large app with a long compile, modularisation wins. For a small app, it can lose. The honest answer is to measure both phases before and after, which --profile makes possible.

The build as a program you maintain#

A Gradle build script is code, and it accumulates the same problems as any other code: duplication, hidden coupling, and logic that seemed reasonable at the time.

Two patterns show up in almost every mature project.

Convention plugins. A build-logic included build defines plugins that configure a module the way the project expects — the same compile SDK, the same Kotlin options, the same lint config. A module then applies one plugin instead of repeating thirty lines. The win is not brevity; it is that changing a convention changes every module at once.

Build logic in tasks, not in scripts. Reading a file, computing a version, generating source — all of these belong in a task with declared inputs and outputs, where Gradle can cache them and where the configuration phase does not pay for them.

The smell to watch for is a build script that gets slower as the project grows. That is almost always work in the configuration phase that should have been a task.

A checklist for a slow build#

In order, because each step is cheaper than the next.

1. Run --profile and read whether configuration or execution dominates.
2. If configuration dominates, enable the configuration cache and fix what breaks.
3. If execution dominates, enable the build cache and a remote cache for CI.
4. Look for annotation processors: kapt is the single most expensive common task.
5. Check for a buildSrc change invalidating everything; consider build-logic instead.
6. Only then consider hardware or parallelism.

Most teams stop at step one and guess. The profile report is free and answers the question directly.

How it evolved#

Under the hood#

• ‹›settings.gradle.kts↗which projects are in the build; the first thing read
• ‹›build.gradle.kts↗root project configuration, usually just plugin versions
• ‹›gradle.properties↗build-wide flags such as the configuration cache and JVM args
• ‹›libs.versions.toml↗the version catalog, read during configuration
• ‹›↗the HTML timing report produced by --profile

Curiosity corner#

• --dry-run still configures. It prints the task graph, which means it pays the full configuration cost. A dry run that takes a minute is telling you something.
• Gradle's daemon is why the second build is faster than the first. A JVM is kept warm between invocations; ./gradlew --stop throws that away.
• clean is usually the wrong fix. It deletes the build directory, which is the cache. If a clean build works and an incremental one does not, the bug is an undeclared input.

Try it#

$ 
./gradlew :app:assembleDebug --profile

See build/reports/profile/profile-*.html

$ 
./gradlew :app:assembleDebug --info | grep -A2 "Task :app:compileDebugKotlin"

> Task :app:compileDebugKotlin
  Input property 'source' file changed: app/src/main/java/.../Main.kt

$ 
./gradlew :app:assembleDebug --configuration-cache

Configuration cache entry stored.
BUILD SUCCESSFUL in 4s

Build it#

Add org.gradle.configuration-cache=true to gradle.properties on a project you own and run the build twice. The difference between the first and second run is the configuration phase disappearing.

Check yourself#

Sources#