Upgrading your build from Gradle 8.x to the latest

This chapter provides the information you need to migrate your Gradle 8.x builds to the latest Gradle release. For migrating from Gradle 4.x, 5.x, 6.x, or 7.x, see the older migration guide first.

We recommend the following steps for all users:

Try running gradle help --scan and view the deprecations view of the generated build scan.

This is so you can see any deprecation warnings that apply to your build.

Alternatively, you could run gradle help --warning-mode=all to see the deprecations in the console, though it may not report as much detailed information.
Update your plugins.

Some plugins will break with this new version of Gradle, for example because they use internal APIs that have been removed or changed. The previous step will help you identify potential problems by issuing deprecation warnings when a plugin does try to use a deprecated part of the API.
Run gradle wrapper --gradle-version 8.1-20230219160000+0000 to update the project to 8.1-20230219160000+0000.
Try to run the project and debug any errors using the Troubleshooting Guide.

Upgrading from 8.0 and earlier

Potential breaking changes

Kotlin DSL scripts emit compilation warnings

Compilation warnings from Kotlin DSL scripts are printed to the console output. For example, the use of deprecated APIs in Kotlin DSL will emit warnings each time the script is compiled.

This is a potentially breaking change if you are consuming the console output of Gradle builds.

Deprecations

Custom configuration roles

Custom roles have been deprecated. Use a pre-defined role instead.

Allowed configurations usage

The usage of configurations should be fixed at creation. Mutating the allowed usage on a configuration is deprecated. This includes calling any of the following Configuration methods:

setCanBeConsumed(boolean)
setCanBeResolved(boolean)

The ability to change the allowed usage of a configuration after creation will be removed in Gradle 9.0.

Calling select methods on the `JavaPluginExtension` without the `java` component present

Starting in Gradle 8.1, calling any of the following methods on JavaPluginExtension without the presence of the default java component is deprecated:

withJavadocJar()
withSourcesJar()
consistentResolution(Action)

This java component is added by the JavaPlugin, which is applied by any of the Gradle JVM plugins including:

java-library
application
groovy
scala

Starting in Gradle 9.0, calling any of the above listed methods without the presence of the default java component will become an error.

`WarPlugin#configureConfiguration(ConfigurationContainer)`

Starting in Gradle 8.1, calling WarPlugin#configureConfiguration(ConfigurationContainer) is deprecated. This method was intended for internal use and was never intended to be used as part of the public interface.

Starting in Gradle 9.0, this method will be removed without replacement.

Relying on Test task default testClassesDirs and classpath

By default, when applying the JavaPlugin, standalone Test tasks are configured such that their testClassesDirs and classpath mirror the corresponding values in the default test TestSuite. This behavior will be removed in Gradle 9.0.

For most use cases, this existing default behavior is unnecessary, since most standalone test tasks are used to model separate test suites and thus run a separate set of tests than those of the default test task. For more information on how to properly configure a standalone test task to compile and run against a separate set of tests, see Configuring integration tests.

However, this existing default behavior can be restored for a given test named myTestTask with the following code:

build.gradle.kts

tasks.named<Test>("myTestTask") {
    testClassesDirs = tasks.test.get().testClassesDirs
    classpath = tasks.test.get().classpath
}

build.gradle

tasks.myTestTask {
    testClassesDirs = tasks.test.testClassesDirs
    classpath = tasks.test.classpath
}

Modifying Gradle Module Metadata after a publication has been populated

Altering the GMM (e.g., changing a component configuration variants) after a Maven or Ivy publication has been populated from their components is now deprecated. This feature will be removed in Gradle 9.0.

Eager population of the publication can happen if the following methods are called:

Previously, the following code did not generate warnings, but it created inconsistencies between published artifacts:

build.gradle.kts

publishing {
    publications {
        create<MavenPublication>("maven") {
            from(components["java"])
        }
        create<IvyPublication>("ivy") {
            from(components["java"])
        }
    }
}

// These calls eagerly populate the Maven and Ivy publications

(publishing.publications["maven"] as MavenPublication).artifacts
(publishing.publications["ivy"] as IvyPublication).artifacts

val javaComponent = components["java"] as AdhocComponentWithVariants
javaComponent.withVariantsFromConfiguration(configurations["apiElements"]) { skip() }
javaComponent.withVariantsFromConfiguration(configurations["runtimeElements"]) { skip() }

build.gradle

publishing {
    publications {
        maven(MavenPublication) {
            from components.java
        }
        ivy(IvyPublication) {
            from components.java
        }
    }
}

// These calls eagerly populate the Maven and Ivy publications

publishing.publications.maven.artifacts
publishing.publications.ivy.artifacts

components.java.withVariantsFromConfiguration(configurations.apiElements) { skip() }
components.java.withVariantsFromConfiguration(configurations.runtimeElements) { skip() }

In this example, the Maven and Ivy publications will contain the main JAR artifacts for the project, whereas the GMM module file will omit them.

Running tests on JVM versions 6 and 7

Running JVM tests on JVM versions older than 8 is deprecated. Testing on these versions will become an error in Gradle 9.0

Applying Kotlin DSL precompiled scripts published with Gradle < 6.0

Applying Kotlin DSL precompiled scripts published with Gradle < 6.0 is deprecated. Please use a version of the plugin published with Gradle >= 6.0.

Applying the `kotlin-dsl` together with Kotlin Gradle Plugin < 1.8.0

Applying the kotlin-dsl together with Kotlin Gradle Plugin < 1.8.0 is deprecated. Please let Gradle control the version of kotlin-dsl by removing any explicit kotlin-dsl version constraints from your build logic. This will let the kotlin-dsl plugin decide which version of the Kotlin Gradle Plugin to use. If you explicitly declare which version of the Kotlin Gradle Plugin to use for your build logic, update it to >= 1.8.0.

Accessing `libraries` or `bundles` from dependency version catalogs in the `plugins {}` block of a Kotlin script

Accessing libraries or bundles from dependency version catalogs in the plugins {} block of a Kotlin script is deprecated. Please only use versions or plugins from dependency version catalogs in the plugins {} block.

Using `ValidatePlugins` task without a Java Toolchain

Using a task of type ValidatePlugins without applying the Java Toolchains plugin is deprecated, and will become an error in Gradle 9.0.

To avoid this warning, please apply the plugin to your project:

build.gradle.kts

plugins {
    id("jdk-toolchains")
}

build.gradle

plugins {
    id 'jdk-toolchains'
}

The Java Toolchains plugin is applied automatically by the Java plugin, so you can also apply it to your project and it will fix the warning.

Deprecated members of the `org.gradle.util` package now report their deprecation

These members will be removed in Gradle 9.0.

VersionNumber
WrapUtil.toDomainObjectSet(…)
GUtil.toCamelCase(…)
GUtil.toLowerCase(…)
ConfigureUtil.configureByMap(…)

Deprecated JVM vendor IBM Semeru

The enum constant JvmVendorSpec.IBM_SEMERU is now deprecated and will be removed in Gradle 9.0.

Please replace it by its equivalent JvmVendorSpec.IBM to avoid warnings and potential errors in the next major version release.

Setting custom build layout on `StartParameter` and `GradleBuild`

Following the related previous deprecation of the behaviour in Gradle 7.1, it is now also deprecated to use related StartParameter and GradleBuild properties. These properties will be removed in Gradle 9.0.

Setting custom build file using buildFile property in GradleBuild task has been deprecated.

Please use the dir property instead to specify the root of the nested build. Alternatively, consider using one of the recommended alternatives for GradleBuild task as suggested in Avoid using the GradleBuild task type section.

Setting custom build layout using StartParameter methods setBuildFile(File) and setSettingsFile(File) as well as the counterpart getters getBuildFile() and getSettingsFile() have been deprecated.

Please use standard locations for settings and build files:

settings file in the root of the build
build file in the root of each subproject

Deprecated org.gradle.cache.cleanup property

The org.gradle.cache.cleanup property in gradle.properties under Gradle user home has been deprecated. Please use the cache cleanup DSL instead to disable or modify the cleanup configuration.

Since the org.gradle.cache.cleanup property may still be needed for older versions of Gradle, this property may still be present and no deprecation warnings will be printed as long as it is also configured via the DSL. The DSL value will always take preference over the org.gradle.cache.cleanup property. If the desired configuration is to disable cleanup for older versions of Gradle (using org.gradle.cache.cleanup), but to enable cleanup with the default values for Gradle versions at or above Gradle 8, then cleanup should be configured to use Cleanup.DEFAULT:

cache-settings.gradle

if (GradleVersion.current() >= GradleVersion.version('8.0')) {
    apply from: "gradle8/cache-settings.gradle"
}

cache-settings.gradle.kts

if (GradleVersion.current() >= GradleVersion.version("8.0")) {
    apply(from = "gradle8/cache-settings.gradle")
}

gradle8/cache-settings.gradle

beforeSettings { settings ->
    settings.caches {
        cleanup = Cleanup.DEFAULT
    }
}

gradle8/cache-settings.gradle.kts

beforeSettings {
    caches {
        cleanup.set(Cleanup.DEFAULT)
    }
}

Changes in the IDE integration

Workaround for false positive errors shown in Kotlin DSL `plugins {}` block using version catalog is not needed anymore

Version catalog accessors for plugin aliases in the plugins {} block aren’t shown as errors in IntelliJ IDEA and Android Studio Kotlin script editor anymore.

If you were using the @Suppress("DSL_SCOPE_VIOLATION") annotation as a workaround, you can now remove it.

If you were using the Gradle Libs Error Suppressor IntelliJ IDEA plugin, you can now uninstall it.

After upgrading Gradle to 8.1 you will need to clear the IDE caches and restart.

Also see the deprecated usages of version catalogs in the Kotlin DSL plugins {} block above.