iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
jvmToolchain(N) asks the Kotlin Gradle Plugin to use a Java toolchain with language version N for the JVM build. In a typical Kotlin/JVM project, that can replace manually repeating Java compatibility settings to keep Java and Kotlin compilation aligned. It does not, by itself, replace every bytecode-target choice or compiler flag.
What jvmToolchain(N) does
The number N is the requested Java language version for the toolchain—for example, 17 requests a Java 17 toolchain. A Gradle toolchain is a JDK or JRE selected for tasks that need Java tools, such as compilation. Gradle may use an installed toolchain or provision one according to its setup. It is a requirement for build tools, not simply a label for the bytecode your application will emit. Gradle’s toolchain guide describes toolchains as task tool requirements; the JavaToolchainSpec API defines the language version as the exact Java language version required.
Kotlin/JVM example
For a project applying the Kotlin/JVM plugin, declare the toolchain in the Kotlin extension:
Recommended Free Tools
kotlin {
jvmToolchain(17)
}This is Kotlin Gradle Plugin DSL. It is not a universal Gradle or Android setting, and the example assumes the Kotlin/JVM plugin is applied. Check the compatibility information for the Kotlin Gradle Plugin and Gradle versions actually used in your project.
Why it can replace a manual compatibility block
Without a shared toolchain configuration, a JVM project may configure Java and Kotlin compilation separately, then have to keep their target versions consistent. Kotlin documents toolchain setup as a way to avoid incompatible JVM targets between related Kotlin and Java compile tasks. Gradle’s Java plugin toolchain also supplies compatibility values from the toolchain rather than from sourceCompatibility or targetCompatibility. Together, these behaviors make one toolchain declaration a simpler way to express the intended Java version in common JVM builds.
That is the qualified sense in which jvmToolchain(N) replaces a compileOptions-style block: it can remove redundant manual Java compatibility configuration when the toolchain provides the behavior the project needs. It does not make all target and compiler configuration obsolete.
Rank #2
Toolchain version, bytecode target, and compiler flags are different
| Setting | What it controls | When you may still need it |
|---|---|---|
jvmToolchain(N) |
The Java toolchain language version used to select tools for relevant build tasks. | Use it to express which Java toolchain the build should use. |
Kotlin jvmTarget |
The JVM target configured for Kotlin compilation. | Set it explicitly when the emitted Kotlin bytecode must target a particular JVM level. |
Java targetCompatibility |
The Java compilation target compatibility setting documented separately from toolchain selection. | Configure it deliberately if the project has a specific Java output target requirement. |
| Compiler options | Individual compiler behavior and flags, rather than toolchain selection. | Retain or add the options your project actually requires; a toolchain declaration does not imply them. |
Kotlin’s Gradle configuration documentation treats jvmTarget and Java targetCompatibility as explicit settings distinct from toolchain setup. If your build must emit bytecode for a level different from the toolchain version, state that target explicitly and verify the configuration supported by your plugin versions.
Keep related Java and Kotlin tasks compatible
Kotlin checks JVM target compatibility for related task pairs, including compileKotlin with compileJava and compileTestKotlin with compileTestJava. A mismatch can produce a warning or an error depending on the Gradle version and validation mode. Kotlin’s current documentation says the default is an error with Gradle 8.0 and later, and a warning on earlier Gradle versions. A shared toolchain can help align these tasks, but explicit target settings still need to agree.
Android is a separate DSL context
Do not mechanically replace an Android Gradle Plugin compileOptions block with Kotlin/JVM’s jvmToolchain(N) syntax. Android’s compileOptions belongs to the Android plugin’s DSL; it is not interchangeable with the Kotlin/JVM plugin configuration shown above. For an Android build, check the documentation for the Android Gradle Plugin and Kotlin Gradle Plugin versions in use, and configure Java and Kotlin targets using the APIs those versions support.
What it does not change: the JVM running Gradle
A Java toolchain configures tools for build tasks that request them. It should not be treated as a setting that changes the JVM process running Gradle itself. Gradle’s runtime JVM and the toolchain selected for compilation are distinct concerns; configure and verify them separately when the build has runtime requirements.
Rank #4
Migration checklist
- Confirm the project applies Kotlin/JVM before adding
kotlin { jvmToolchain(N) }. - Choose
Nfor the Java toolchain the build tasks should use. - Remove redundant Java compatibility settings only if the toolchain provides the intended behavior for the applied Java plugin and Gradle version. Gradle specifically documents that configuring the Java extension’s toolchain cannot be combined with
sourceCompatibilityortargetCompatibilityon that extension; do not assume this restriction applies identically to every plugin’s similarly named DSL. - Keep explicit Kotlin
jvmTarget, Java target compatibility, or compiler flags when the project requires those settings. - Run the build and resolve any JVM target compatibility warning or error between related Java and Kotlin tasks.
- For Android, verify the relevant Android and Kotlin plugin documentation rather than substituting Kotlin/JVM syntax for Android DSL configuration.
Version compatibility changes over time. The Kotlin configuration documentation currently identifies KGP 2.4.20 as fully supported with Gradle 7.6.3–9.7.0 and AGP 8.5.2–9.3.1; confirm the current compatibility information for the versions you plan to use.
Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
