skip to content

How are AGP, Gradle, and the JDK versions related, and how do you manage upgrades?

level: middleimportance: should knowfreq 45%

answer

  1. AGP / Gradle / JDK — three axes
  2. AGP in version catalog, Gradle in wrapper.properties
  3. Google compatibility matrix + min JDK
  4. AGP Upgrade Assistant
  5. pin all three in CI

basics

~10 s

AGP and Gradle version independently but each AGP requires a minimum Gradle and JDK. You set AGP in the plugins/version catalog and Gradle in gradle-wrapper.properties. Use Google's compatibility matrix and upgrade them together.

solid answer

~50 s

AGP, the Gradle distribution, and the JDK are three separate versions you control independently — but they have **compatibility constraints**. Each AGP release declares a *minimum* (and effectively a maximum-tested) Gradle version and a minimum JDK to run the build. You declare the AGP version where you apply the plugin (typically via a version catalog `libs.versions.toml`), and you pin the Gradle version in `gradle/wrapper/gradle-wrapper.properties`. The JDK that runs Gradle is set by `JAVA_HOME` / toolchain config. When upgrading, consult Google's AGP-to-Gradle compatibility table: bumping AGP usually forces a Gradle wrapper bump and sometimes a newer JDK. Android Studio's **AGP Upgrade Assistant** automates much of this and applies migration changes. Keeping them in lockstep avoids cryptic failures like 'Minimum supported Gradle version is X' or unsupported-class-file-version errors. In CI, pin all three explicitly so builds are reproducible.

code

toml · 8 lines
toml
# gradle/libs.versions.toml
[versions]
agp = "8.4.0"
kotlin = "1.9.24"

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

go deeper

for a junior

Know AGP and Gradle are different versions and that AGP needs a minimum Gradle; mention the wrapper file.

for a middle

Explain the three axes (AGP/Gradle/JDK), where each is declared, and using the compatibility matrix when upgrading.

for a senior

Discuss the Upgrade Assistant, deprecated-DSL removals across AGP majors, and pinning all three in CI for reproducibility.

for a principal

Define an upgrade governance policy across many modules/teams: coordinated bumps, deprecation tracking, and CI gates to prevent version drift.

## Three independent-but-coupled versions An Android build has three version axes: 1. **AGP version** — the Android Gradle Plugin itself, e.g. `8.4.0`. 2. **Gradle version** — the build engine distribution, e.g. `8.6`. 3. **JDK version** — the Java runtime that *executes* Gradle (distinct from `compileSdk`, which is about Android APIs). They are declared in different places: ```toml # gradle/libs.versions.toml [versions] agp = "8.4.0" [plugins] android-application = { id = "com.android.application", version.ref = "agp" } ``` ```properties # gradle/wrapper/gradle-wrapper.properties distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip ``` The JDK is chosen by `JAVA_HOME` (or your CI's Java setup); note this is the build JDK, separate from the `compileSdk`/`targetSdk` Android API levels and from any Java *toolchain* you configure for compiling sources. ## The compatibility matrix Google publishes an **AGP ↔ Gradle compatibility table** and a **minimum JDK** per AGP. Each AGP needs *at least* a given Gradle version; using too old a Gradle triggers an error like: ```text Minimum supported Gradle version is 8.6. Current version is 8.2. ``` Using too old a JDK can yield `Unsupported class file major version` errors. ## Upgrade strategy - Bump versions **together**, checking the matrix: a major AGP bump typically requires a Gradle wrapper bump and may raise the minimum JDK. - Use **Android Studio's AGP Upgrade Assistant**, which edits the catalog/build files and applies known migrations and removals of deprecated DSL. - Read AGP release notes for **removed/deprecated DSL** (AGP regularly deletes long-deprecated APIs across majors). - In **CI**, pin AGP (catalog), Gradle (wrapper), and JDK (setup-java/toolchain) explicitly so builds are reproducible and don't silently drift. ## Why decoupling exists Decoupling lets the Gradle engine and the Android plugin evolve on their own cadences; the matrix exists precisely because they must still interoperate. Treat the trio as a coordinated upgrade unit rather than three independent knobs.

  • Where do you change the Gradle version for an AGP upgrade?
    In gradle/wrapper/gradle-wrapper.properties via the distributionUrl, ideally using ./gradlew wrapper --gradle-version=X so the wrapper jar/scripts stay consistent.
  • Is the build JDK the same as compileSdk?
    No. The build JDK is the Java runtime that executes Gradle and compiles JVM bytecode. compileSdk is the Android API level you compile against. They are unrelated version axes.
  • What error do you typically see when Gradle is too old for the chosen AGP?
    A message like 'Minimum supported Gradle version is X. Current version is Y', failing configuration until you bump the wrapper.

saying these in an interview costs you the question

  • Saying AGP and Gradle must share the exact same version number — they don't; they share a compatibility range.
  • Confusing the build JDK with compileSdk/targetSdk.
  • Upgrading AGP without bumping the Gradle wrapper and hitting a minimum-version error.

context

resolving links…