# Upgrading within Gradle 9.x.y

version 9.3.0-20251010091952+0000

This chapter provides the information you need to migrate your Gradle 9.x.y builds to the latest. For migrating to Gradle 9.0.0, see the older migration guide first.

We recommend the following steps for all users:

1. Try running `gradle help --scan` and view the deprecations view of the generated Build Scan.

   This lets you see any deprecation warnings that apply to your build.

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

2. Update your plugins.

   Some plugins will break with this new version of Gradle 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 tries to use a deprecated part of the API.

3. Run `gradle wrapper --gradle-version 9.3.0-20251010091952+0000` to update the project to 9.3.0-20251010091952+0000.

4. Try to run the project and debug any errors using the Troubleshooting Guide.

## Upgrading from 9.2.0 and earlier

### Deprecations

#### Deprecated `Wrapper.getAvailableDistributionTypes()` method

The method on the Wrapper task has been deprecated and will be removed in Gradle 10.

Use `Wrapper.DistributionType.values()` to obtain the available distribution types instead.

## Upgrading from 9.1.0 and earlier

### Potential breaking changes

#### Upgrade to Kotlin 2.2.20

The embedded Kotlin has been upgraded from 2.2.0 to Kotlin 2.2.20.

#### Removed incubating `ObjectFactory#dependencyCollector()` method

The incubating `ObjectFactory#dependencyCollector()` method has been removed. You can still create `DependencyCollectors` within Gradle managed types.

#### Consumable configurations in bundled plugins are now initialized lazily

Consumable configurations created by bundled Gradle plugins are now initialized only when needed. `Configure` actions on these configurations no longer run at configuration time by default. They only execute if the configuration is published, consumed as a variant, or otherwise realized by build logic.

For example:

build.gradle.kts

    plugins {
        id("java-library")
    }

    configurations.named("apiElements").configure {
        println("Configuring apiElements")
    }

With this change, the `Configuring apiElements` line is no longer printed during configuration time unless `apiElements` is actually realized.

See Declaring Configurations for more guidance.

### Deprecations

#### Deprecated `Project.container(…​)` methods

The `Project.container(…​)` methods are deprecated and will be removed in Gradle 10. These methods manually create named domain object containers.

Use a managed property to let Gradle instantiate containers automatically. If a managed property isn’t possible, use `ObjectFactory.domainObjectContainer(…​)` (available since Gradle 5.5). Unlike `Project.container(Class)`, the `ObjectFactory` version decorates container elements and makes them extension aware.

#### Deprecated ruleSource-based dependency management APIs

The `RuleSource`-based dependency management APIs have been deprecated and will be removed in Gradle 10.0.0.

Deprecated APIs include:

- `ComponentMetadataHandler.all(Object)`

- `ComponentMetadataHandler.withModule(Object,Object)`

- `ComponentSelectionRules.all(Object)`

- `ComponentSelectionRules.withModule(Object,Object)`

Use the alternative methods that accept a `ComponentMetadataRule` class or an `Action`.

#### Deprecated calling `registerFeature` without applying the Java plugin

Creating a JVM feature with `JavaPluginExtension#registerFeature` before applying the Java plugin has been deprecated and will become an error in Gradle 10.0.0.

Ensure the Java plugin is applied before invoking `registerFeature`. The following bundled plugins apply the Java plugin automatically:

- `java-library`

- `application`

- `groovy`

- `scala`

- `war`

## Upgrading from 9.0.0 and earlier

### Potential breaking changes

#### Upgrade to ASM 9.8

ASM was upgraded from 9.7.1 to 9.8 to ensure earlier compatibility for Java 25.

#### Upgrade to Groovy 4.0.28

Groovy has been updated to Groovy 4.0.28.

### Deprecations

#### Deprecation of multi-string dependency notation

In an effort to simplify and standardize the Gradle API, the multi-string dependency notation used in dependency management has been deprecated and will no longer be permitted in Gradle 10. Gradle will primarily accept dependency declarations in the form of a single string, with each dependency coordinate separated by a colon.

Below are examples of the deprecated multi-string notation:

build.gradle.kts

    dependencies {
        implementation(group = "org", name = "foo", version = "1.0")
        implementation(group = "org", name = "foo", version = "1.0", configuration = "conf")
        implementation(group = "org", name = "foo", version = "1.0", classifier = "classifier")
        implementation(group = "org", name = "foo", version = "1.0", ext = "ext")
    }

    testing.suites.named<JvmTestSuite>("test") {
        dependencies {
            implementation(module(group = "org", name = "foo", version = "1.0"))
        }
    }

build.gradle

    dependencies {
        implementation(group: 'org', name: 'foo', version: '1.0')
        implementation(group: 'org', name: 'foo', version: '1.0', configuration: 'conf')
        implementation(group: 'org', name: 'foo', version: '1.0', classifier: 'classifier')
        implementation(group: 'org', name: 'foo', version: '1.0', ext: 'ext')
    }

    testing.suites.test {
        dependencies {
            implementation(module(group: 'org', name: 'foo', version: '1.0'))
        }
    }

These declarations should be replaced with the single-string notation:

build.gradle.kts

    dependencies {
        implementation("org:foo:1.0")
        implementation("org:foo:1.0") {
            targetConfiguration = "conf"
        }
        implementation("org:foo:1.0:classifier")
        implementation("org:foo:1.0@ext")
    }

    testing.suites.named<JvmTestSuite>("test") {
        dependencies {
            implementation("org:foo:1.0")
        }
    }

build.gradle

    dependencies {
        implementation("org:foo:1.0")
        implementation("org:foo:1.0") {
            targetConfiguration = "conf"
        }
        implementation("org:foo:1.0:classifier")
        implementation("org:foo:1.0@ext")
    }

    testing.suites.test {
        dependencies {
            implementation("org:foo:1.0")
        }
    }

In some cases, a complete single-string notation may not be known up front. Instead of concatenating the coordinates into a new string, it is possible to use a `DependencyFactory` to create `Dependency` instances directly from the individual components:

build.gradle.kts

    val group = "org"
    val artifactId = "foo"
    val version = "1.0"

    configurations.dependencyScope("implementation") {
        dependencies.add(project.dependencyFactory.create(group, artifactId, version))
    }

build.gradle

    def group = "org"
    def artifactId = "foo"
    def version = "1.0"

    configurations.dependencyScope("implementation") {
        dependencies.add(project.dependencyFactory.create(group, artifactId, version))
    }

#### Deprecation of `ReportingExtension.file(String)`

The `file()` method on `ReportingExtension` has been deprecated and will be removed in Gradle 10.0.0.

Instead, use `ReportingExtension.getBaseDirectory()` with `file(String)` or `dir(String)`.

#### Deprecation of `ReportingExtension.getApiDocTitle()`

The `getApiDocTitle()` method on `ReportingExtension` has been deprecated and will be removed in Gradle 10.0.0.

There is no direct replacement for this method.

#### Deprecation of `JavaForkOptions.setAllJvmArgs()`

The `setAllJvmArgs()` method on `JavaForkOptions` and, by inheritance, on `JavaExecSpec` has been deprecated and will be removed in Gradle 10.0.0.

Instead, to overwrite existing JVM arguments, use:

- `JavaForkOptions.jvmArgs()`

- `JavaForkOptions.setJvmArgs()`

- Provide a `CommandLineArgumentProvider` to add arguments via `JavaForkOptions.getJvmArgumentProviders()`

Note that `setAllJvmArgs()` method on `JavaForkOptions` cleared all fork options before setting `jvmArgs`. The properties cleared included:

- System properties configured via `JavaForkOptions.systemProperties`

- JVM argument providers configured via `JavaForkOptions.jvmArgumentProviders`

- Argument providers configured via `JavaExecSpec.argumentProviders`

- Memory settings configured via `JavaForkOptions.minHeapSize` and `JavaForkOptions.maxHeapSize`

- All other JVM arguments configured via `JavaForkOptions.jvmArgs`

- The assertion and debug flags configured via `JavaForkOptions.enableAssertions` and `JavaForkOptions.debug`

If the arguments you provide to `setJvmArgs()` or `jvmArgs()` depend on any of the above properties being cleared, you will need to manually clear them.

Consider the following snippets for examples of how to implement this change:

build.gradle.kts

    plugins {
        id("java")
    }

    tasks.register<JavaExec>("myRunTask") {
        jvmArgumentProviders.clear() // Clear existing JVM argument providers
        maxHeapSize = null // Clear max heap size
        jvmArgs = listOf("-Dfoo", "-Dbar") // Set new JVM arguments
    }

build.gradle

    plugins {
        id("java")
    }

    tasks.named('myRunTask', JavaExec) {
        jvmArgumentProviders.clear() // Clear existing JVM argument providers
        maxHeapSize = null // Clear max heap size
        jvmArgs = ["-Dfoo", "-Dbar"] // Set new JVM arguments
    }

#### Deprecation of `archives` configuration

The `archives` configuration added by the `base` plugin has been deprecated and will be removed in Gradle 10.0.0. Adding artifacts to the `archives` configuration will now result in a deprecation warning.

If you want the artifact to be built when running the `assemble` task, add the artifact (or the task that produces it) as a dependency on `assemble`:

build.gradle.kts

    val specialJar = tasks.register<Jar>("specialJar") {
        archiveBaseName.set("special")
        from("build/special")
    }

    tasks.named("assemble") {
        dependsOn(specialJar)
    }

#### Deprecation of the `Configuration.visible` property

Prior to Gradle 9.0.0, any configuration with `isVisible()` returning `true` would implicitly trigger artifact creation when running the `assemble` task. This behavior was removed in Gradle 9.0.0, and the `Configuration.visible` property no longer has any effect. The property is now deprecated and will be removed in Gradle 10.0.0. You can safely remove any usage of `visible`.

If you want the artifacts of a configuration to be built when running the `assemble` task, add an explicit task dependency on `assemble`:

build.gradle.kts

    val specialJar = tasks.register<Jar>("specialJar") {
        archiveBaseName.set("special")
        from("build/special")
    }

    configurations {
        consumable("special") {
            outgoing.artifact(specialJar)
        }
    }

    tasks.named("assemble") {
        dependsOn(specialJar)
    }

#### Deprecation of non-string `projectProperties` in `GradleBuild` task

The `GradleBuild` task now deprecates using non-String values in `startParameter.projectProperties`. While the type is declared as `Map<String, String>`, there was no strict enforcement, allowing non-String values to be set. This deprecated behavior will be removed in Gradle 10.0.0.

If you are using non-String values in project properties, convert them to `String` representation:

build.gradle.kts

    val myIntProp = 42

    tasks.register<GradleBuild>("nestedBuild") {
        startParameter.projectProperties.put("myIntProp", "$myIntProp") // Convert int to String
    }

build.gradle

    def myIntProp = 42

    tasks.register('nestedBuild', GradleBuild) {
        startParameter.projectProperties.put('myIntProp', "$myIntProp") // Convert int to String
    }

#### Deprecation of project properties for toolchain configuration

In previous versions of Gradle, you could configure toolchains using project properties on the command line with the `-P` flag. For example, to disable toolchain auto-detection, you could use `-Porg.gradle.java.installations.auto-detect=false`. This behavior is deprecated and will be removed in Gradle 10.0.0. Instead, you should specify these settings as Gradle properties using the `-D` flag:

    -Dorg.gradle.java.installations.auto-detect=false