Gradle Release Notes

Upgrade instructions

Switch your build to use Gradle 8.2.1 by updating your wrapper:

./gradlew wrapper --gradle-version=8.2.1

See the Gradle 7.x upgrade guide to learn about deprecations, breaking changes and other considerations when upgrading to Gradle 8.2.1.

For Java, Groovy, Kotlin and Android compatibility, see the full compatibility notes.

New features, performance and usability improvements

Kotlin DSL improvements

Gradle's Kotlin DSL provides an enhanced editing experience in supported IDEs compared to the traditional Groovy DSL — auto-completion, smart content assist, quick access to documentation, navigation to source, and context-aware refactoring.

Kotlin DSL has received substantial improvements in the recent releases, leading to the announcement that Kotlin DSL is Now the Default for New Gradle Builds. This release brings another series of improvements.

Kotlin DSL reference

A brand new reference documentation for the Gradle Kotlin DSL is now published and versioned alongside the user manual.

You can use the Kotlin DSL reference search functionality to drill through the APIs.

Simple property assignment in Kotlin DSL enabled by default

The last release introduced the simpler way to assign values to lazy property types in Kotlin scripts using the = operator instead of the set() method. This new assignment operator is now available by default.

interface Extension {
    val description: Property<String>
}

// register "extension" with type Extension
extension {
    // Using the set() method call
    description.set("Hello Property")
    // Incubating: using lazy property assignment
    description = "Hello Property"
}

This feature is still incubating. In case of any issues you can opt-out by adding systemProp.org.gradle.unsafe.kotlin.assignment=false to the gradle.properties file.

For more information see Kotlin DSL Primer and Simpler Kotlin DSL Property Assignment blog post.

Gradle init defaults to the Kotlin DSL

Starting with this release, generating a new project with the gradle init command now defaults to using the Kotlin DSL instead of Groovy DSL.

In interactive mode you can choose which DSL to use and the Kotlin one is now listed first:

Select build script DSL:
  1: Kotlin
  2: Groovy
Enter selection (default: Kotlin) [1..2]

See the build init user manual chapter for more information.

Fail on script compilation warnings

Gradle Kotlin DSL scripts are compiled by Gradle during the configuration phase of your build. For example, deprecation warnings or unused variables found by the Kotlin compiler are reported on the console when compiling the scripts.

In order to catch potential issues faster, it is now possible to configure your build to fail on any warning emitted during script compilation by setting the org.gradle.kotlin.dsl.allWarningsAsErrors Gradle property to true:

# gradle.properties
org.gradle.kotlin.dsl.allWarningsAsErrors=true

More details can be found in the dedicated section of the Kotlin DSL user manual chapter.

Sync memory consumption

Sync happens with the Tooling API - a programmatic interface that enables external tools and systems to interact with Gradle builds seamlessly.

The performance of the sync process generally depends on the stack being used for the build, including the IDE, Gradle, and any associated plugins.

Performance results measured for a large Android project sync with Android Studio Flamingo:

• The 8.0 client + 8.0 daemon is the Android Studio Flamingo stack you could use with prior to today
• The 8.0 client + 8.2 daemon is the stack with Gradle 8.2. This is what you can expect after upgrading to 8.2
• The 8.2 client + 8.2 daemon is the future Android Studio Hedgehog stack with Gradle 8.2

IDEA users can also expect the same benefits after upgrading Gradle to 8.2, although sync performance in the future IDEA releases will slightly differ from presented numbers for Android Studio.

Improved console output

In the new release, we have taken the first step towards implementing the clean and actionable error reporting item from our public roadmap, by making a number of improvements to the console output in case of build failures.

Suggestions that were previously a part of the error message are now displayed in the * Try section, making them more noticeable. Additionally, the output is streamlined by eliminating unnecessary links to help.gradle.org for recoverable errors, such as compilation failures.

For example, a toolchain selection problem looks like the this on the console:

> Task :compileJava FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':compileJava'.
> Error while evaluating property 'javaCompiler' of task ':compileJava'.
   > Failed to calculate the value of task ':compileJava' property 'javaCompiler'.
  	> No matching toolchains found for requested specification: {languageVersion=14, vendor=ADOPTIUM, implementation=J9} for MAC_OS on aarch64.
     	> No locally installed toolchains match and the configured toolchain download repositories aren't able to provide a match either.

* Try:
> Learn more about toolchain auto-detection at https://docs.gradle.org/8.2/userguide/toolchains.html#sec:auto_detection.
> Learn more about toolchain repositories at https://docs.gradle.org/8.2/userguide/toolchains.html#sub:download_repositories.
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.

BUILD FAILED in 1s
1 actionable task: 1 executed

You can review the complete list of these console output enhancements here.

Wrapper task validates distribution URL

The Gradle Wrapper stores the URL of Gradle distribution in the gradle-wrapper.properties file.

Previously, specifying an invalid URL led to I/O exceptions during the build execution.

Starting from this release, the wrapper task automatically validates the configured distribution URL before writing it to the gradle-wrapper.properties file. This surfaces invalid URLSs early and prevents exceptions at execution time.

For example,

./gradlew wrapper --gradle-version 9.9.9

now fails with

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':wrapper'.
> Test of distribution url https://services.gradle.org/distributions/gradle-9.9.9-bin.zip failed. Please check the values set with --gradle-distribution-url and --gradle-version.

and similarly

./gradlew wrapper --gradle-distribution-url http://localhost:8080/gradlew/invalid

now fails with

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':wrapper'.
> Test of distribution url http://localhost:8080/gradlew/invalid failed. Please check the values set with --gradle-distribution-url and --gradle-version.

More details can be found in the dedicated section of the Gradle Wrapper user manual chapter.

Java toolchains discovery progress display

Using Toolchains is a recommended way of specifying Java versions for JVM projects.

Progress is now displayed during Java toolchains discovery.

This can be especially useful during a cold-start of Gradle for users who have environments with a lot of JVM installations in them.

Dependency verification improvements

To mitigate the security risks and avoid integrating compromised dependencies in your project, Gradle supports dependency verification.

Exported PGP keys are now stripped to contain only necessary data. This feature can significantly reduce the size of the keyring files.

In addition, the exported keyring is sorted by key id and de-duplicated to ensure a consistent ordering of keys, which minimizes potential conflicts when updating the keyring.

In order to benefit from these changes, users will have to generate again their keyring.

Boolean task options generate opposite option

Task options of type boolean, Boolean, and Property<Boolean> now automatically generate an opposite option to make setting the value to false easier in the command-line interface.

This feature lets you conveniently set the Boolean option to false, simply by using the --no- prefix. For example, --no-foo option is generated for the provided option --foo.

See the task options user manual section for more information.

Build init can convert more Maven builds

Using gradle init to convert a multimodule Maven build previously required the child submodule projects’ POMs to reference their parent POM using:

<parent>
  <artifactId>parent-project</artifactId>
  <groupId>com.example</groupId>
  <version>1.0</version>
</parent>

Without these backreferences, the conversion process would fail.

The process has been updated to succeed also when the parent element is absent from the submodules.

Configuration API improvements

Using the Configuration API is a fundamental piece of writing Gradle builds. This is a large and multipurpose API that is easy to accidentally misuse. This release of Gradle will provide additional feedback if configurations are used inconsistently.

Call time configuration usage checking

Certain methods in the Configuration API should only be called when the configuration is in a particular “role” as determined by the isCanBeResolved()/isCanBeConsumed()/isCanBeDeclared() flags. For example, calling shouldResolveConsistentlyWith(Configuration) should only be done on a resolvable Configuration. Calling a method that is not appropriate for a configuration’s current role will now in many cases emit a deprecation warning.

These proper usages are now mentioned on the Configuration type’s javadoc.

Fixed issues

Known issues

Known issues are problems that were discovered post release that are directly related to changes made in this release.

External contributions

We love getting contributions from the Gradle community. For information on contributing, please see gradle.org/contribute.

Reporting problems

If you find a problem with this release, please file a bug on GitHub Issues adhering to our issue guidelines. If you're not sure you're encountering a bug, please use the forum.

We hope you will build happiness with Gradle, and we look forward to your feedback via Twitter or on GitHub.