Gradle User Manual: Version 9.7.0

#structuring-builds, #plugins

Don’t Assume your Plugin is Applied after Another

Gradle’s plugin application is deterministic but opaque. It is difficult to reason about, especially across multiple build scripts, projects, convention plugins, or included builds.

As a result, you should not write build logic or plugins that depend on a specific plugin application order.

Explanation

In a single build.gradle(.kts) file, plugins appear to be applied sequentially:

build.gradle.kts

plugins {
    id("pluginA")
    id("pluginB")
}

build.gradle

plugins {
    id("pluginA")
    id("pluginB")
}

However, in multi-project builds, with multiple build.gradle(.kts) files or a convention plugin, plugin application can be hard to determine:

app/build.gradle.kts

plugins {
    id("pluginA")
    id("pluginB")
}

lib/build.gradle.kts

plugins {
    id("pluginC")
    id("pluginD")
}

app/build.gradle

plugins {
    id("pluginA")
    id("pluginB")
}

lib/build.gradle

plugins {
    id("pluginC")
    id("pluginD")
}

You cannot assume whether pluginA, pluginB, pluginC, or pluginD will be applied first because pluginA could apply pluginD.

Build Engineers

Writing build logic that assumes plugin ordering can lead to brittle behavior and fragile builds that break when project structure changes.

Don’t rely on blocks like allprojects {}, subprojects {}, or afterEvaluate {} that are highly dependent on project structure and file layout. They can be difficult to decipher and may depend on configuration details that are hard to understand completely without running the build.

Avoid build logic that assumes ordering between different projects, included builds, or applied scripts. While the application order is deterministic, minor structural changes (such as adding a new project or renaming an include) can easily result in an unexpected change to that plugin application order.

Plugin Developers

Users should be able to apply your plugin in either order and have it behave correctly:

build.gradle.kts

plugins {
  id("my-plugin")
  id("plugin-i-depend-on")
}

build.gradle

plugins {
  id("my-plugin")
  id("plugin-i-depend-on")
}

build.gradle.kts

plugins {
  id("plugin-i-depend-on")
  id("my-plugin")
}

build.gradle

plugins {
  id("plugin-i-depend-on")
  id("my-plugin")
}

If your plugin only works in one of these cases, it’s relying on plugin order and will be fragile in real builds.

If your plugin cannot function without another plugin, apply it explicitly at the start of Plugin.apply:

MyPlugin.kt

// Ensure required plugin is applied
project.pluginManager.apply("com.example.required-plugin")

MyPlugin.groovy

// Ensure required plugin is applied
project.pluginManager.apply('com.example.required-plugin')

If your plugin only needs to integrate with another plugin when it’s present, react to its application using pluginManager.withPlugin() or plugins.configureEach {}:

MyPlugin.kt

// Configure behavior that depends on required-plugin using the plugin id (preferred)
project.pluginManager.withPlugin("com.example.required-plugin") {  }

// Configure behavior that depends on RequiredPlugin using the plugin class (if no id is available)
project.plugins.configureEach { plugin ->
    when (plugin) { is com.example.RequiredPlugin -> {  } }
}

MyPlugin.groovy

// Configure behavior that depends on required-plugin using the plugin id (preferred)
project.pluginManager.withPlugin('com.example.required-plugin') {  }

// Configure behavior that depends on RequiredPlugin using the plugin class (if no id is available)
project.plugins.configureEach { plugin ->
    if (plugin instanceof com.example.RequiredPlugin) {  }
}

This is order-independent and safe.

Example

Given the following project layout:

.
├── app/
│   └── build.gradle.kts
├── buildSrc/
│   ├── build.gradle.kts
│   └── src/main/kotlin/MyPlugin.kt
├── settings.gradle.kts
└── build.gradle.kts

.
├── app/
│   └── build.gradle
├── buildSrc/
│   ├── build.gradle
│   └── src/main/groovy/MyPlugin.groovy
├── settings.gradle
└── build.gradle

Don’t Do This

This setup makes several assumptions about the java plugin.

In the root build, subprojects {} and afterEvaluate {} obscure when a plugin is applied and attempt to force ordering:

build.gradle.kts

subprojects {
    // Apply the Java plugin to every subproject
    afterEvaluate {
        // This runs after the app subproject’s build script is evaluated and results in an error
        pluginManager.apply("java")
    }
}

build.gradle

subprojects {
    // Apply the Java plugin to every subproject
    afterEvaluate {
        // This runs after the app subproject’s build script is evaluated and results in an error
        apply plugin: 'java'
    }
}

In the app subproject, the build file uses extensions.getByType(…) which assumes java has already been applied:

app/build.gradle.kts

plugins {
    id("myplugin")
}
// Assumes 'java' plugin is present
extensions.getByType<org.gradle.api.plugins.JavaPluginExtension>().apply {
    toolchain.languageVersion.set(JavaLanguageVersion.of(21))
}

app/build.gradle

plugins {
    id 'myplugin'
}
// Assumes 'java' plugin is present
project.extensions.getByType(org.gradle.api.plugins.JavaPluginExtension).with {
    toolchain.languageVersion.set(org.gradle.jvm.toolchain.JavaLanguageVersion.of(21))
}

In the plugin implementation, MyPlugin.kt or MyPlugin.groovy also assumes java is already applied:

buildSrc/src/main/kotlin/MyPlugin.kt

class MyPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        // Assumes 'java' plugin is present
        // WARNING: This will fail if the 'java' plugin hasn't been applied yet.
        project.extensions.getByType(JavaPluginExtension::class.java).toolchain {
            languageVersion.set(JavaLanguageVersion.of(21))
        }
    }
}

buildSrc/src/main/groovy/MyPlugin.groovy

class MyPlugin implements Plugin<Project> {
    void apply(Project project) {
        // Assumes 'java' plugin is present
        // WARNING: This will fail if the 'java' plugin hasn't been applied yet.
        project.extensions.configure(JavaPluginExtension) {
            it.toolchain {
                it.languageVersion.set(JavaLanguageVersion.of(21))
            }
        }
    }
}

Do This Instead

The fixed version removes afterEvaluate and avoids assumptions about when or where the java plugin is applied.

The root build file has been deleted as there is no longer a need to use subprojects {}.

In the app subproject, the build file uses plugins.withPlugin("java") {} to safely configure tasks once java is applied:

app/build.gradle.kts

pluginManager.withPlugin("java") {
    extensions.configure<org.gradle.api.plugins.JavaPluginExtension> {
        toolchain.languageVersion.set(JavaLanguageVersion.of(21))
    }
}

app/build.gradle

project.pluginManager.withPlugin('java') {
    project.extensions.configure(org.gradle.api.plugins.JavaPluginExtension) {
        it.toolchain {
            languageVersion.set(JavaLanguageVersion.of(21))
        }
    }
}

In the plugin implementation, MyPlugin.kt or MyPlugin.groovy explicitly applies the java plugin:

buildSrc/src/main/kotlin/MyPlugin.kt

class MyPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        // If your plugin requires 'java', apply it so order doesn’t matter
        project.pluginManager.apply("java")
        // Now it's safe to configure Java things immediately
        project.extensions.configure(JavaPluginExtension::class.java) {
            toolchain.languageVersion.set(JavaLanguageVersion.of(21))
        }
    }
}

buildSrc/src/main/groovy/MyPlugin.groovy

class MyPlugin implements Plugin<Project> {
    void apply(Project project) {
        // If your plugin requires 'java', apply it so order doesn’t matter
        project.pluginManager.apply('java')
        // Now it's safe to configure Java things immediately
        project.extensions.configure(JavaPluginExtension) {
            it.toolchain {
                it.languageVersion.set(JavaLanguageVersion.of(21))
            }
        }
    }
}

References

Using Plugins

Tags

Do Not Use Internal APIs

Do not use APIs from a package where any segment of the package is internal, or types that have Internal or Impl as a suffix in the name.

Explanation

Using internal APIs is inherently risky and can cause significant problems during upgrades. Gradle and many plugins (such as Android Gradle Plugin and Kotlin Gradle Plugin) treat these internal APIs as subject to unannounced breaking changes during any new Gradle release, even during minor releases. There have been numerous cases where even highly experienced plugin developers have been bitten by their usage of such APIs leading to unexpected breakages for their users.

If you require specific functionality that is missing, it’s best to submit a feature request. As a temporary workaround consider copying the necessary code into your own codebase and extending a Gradle public type with your own custom implementation using the copied code.

Example

Don’t Do This

build.gradle.kts

import org.gradle.api.internal.attributes.AttributeContainerInternal

configurations.create("bad") {
    attributes {
        attribute(Usage.USAGE_ATTRIBUTE, objects.named<Usage>(Usage.JAVA_RUNTIME))
        attribute(Category.CATEGORY_ATTRIBUTE, objects.named<Category>(Category.LIBRARY))
    }
    val badMap = (attributes as AttributeContainerInternal).asMap() // (1)
    logger.warn("Bad map")
    badMap.forEach { (key, value) ->
        logger.warn("$key -> $value")
    }
}

build.gradle

import org.gradle.api.internal.attributes.AttributeContainerInternal

configurations.create("bad") {
    attributes {
        attribute(Usage.USAGE_ATTRIBUTE, objects.named(Usage, Usage.JAVA_RUNTIME))
        attribute(Category.CATEGORY_ATTRIBUTE, objects.named(Category, Category.LIBRARY))
    }
    def badMap = (attributes as AttributeContainerInternal).asMap() // (1)
    logger.warn("Bad map")
    badMap.each {
        logger.warn("${it.key} -> ${it.value}")
    }
}

Casting to AttributeContainerInternal and using toMap() should be avoided as it relies on an internal API.

Do This Instead

build.gradle.kts

configurations.create("good") {
    attributes {
        attribute(Usage.USAGE_ATTRIBUTE, objects.named<Usage>(Usage.JAVA_RUNTIME))
        attribute(Category.CATEGORY_ATTRIBUTE, objects.named<Category>(Category.LIBRARY))
    }
    val goodMap = attributes.keySet().associate { // (1)
        Attribute.of(it.name, it.type) to attributes.getAttribute(it)
    }
    logger.warn("Good map")
    goodMap.forEach { (key, value) ->
        logger.warn("$key -> $value")
    }
}

build.gradle

configurations.create("good") {
    attributes {
        attribute(Usage.USAGE_ATTRIBUTE, objects.named(Usage, Usage.JAVA_RUNTIME))
        attribute(Category.CATEGORY_ATTRIBUTE, objects.named(Category, Category.LIBRARY))
    }
    def goodMap = attributes.keySet().collectEntries {
        [Attribute.of(it.name, it.type), attributes.getAttribute(it as Attribute<Object>)]
    }
    logger.warn("Good map")
    goodMap.each {
        logger.warn("$it.key -> $it.value")
    }
}

Implementing your own version of toMap() that only uses public APIs is a lot more robust.

References

Gradle API

Tags

#upgrades

Set Build Flags in `gradle.properties`

Set Gradle build property flags in the gradle.properties file.

Explanation

Instead of using command-line options or environment variables, set build flags in the root project’s gradle.properties file.

Gradle comes with a long list of Gradle properties, which have names that begin with org.gradle and can be used to configure the behavior of the build tool. These properties can have a major impact on build performance, so it’s important to understand how they work.

You should not rely on supplying these properties via the command-line for every Gradle invocation. Providing these properties via the command line is intended for short-term testing and debugging purposes, but it’s prone to being forgotten or inconsistently applied across environments. A permanent, idiomatic location to set and share these properties is in the gradle.properties file located in the root project directory. This file should be added to source control in order to share these properties across different machines and between developers.

You should understand the default values of the properties your build uses and avoid explicitly setting properties to those defaults. Any change to a property’s default value in Gradle will follow the standard deprecation cycle, and users will be properly notified.

Note	Properties set this way are not inherited across build boundaries when using composite builds.

Example

Don’t Do This

├── build.gradle.kts
└── settings.gradle.kts

├── build.gradle
└── settings.gradle

build.gradle.kts

tasks.register("first") {
    doLast {
        throw GradleException("First task failing as expected")
    }
}

tasks.register("second") {
    doLast {
        logger.lifecycle("Second task succeeding as expected")
    }
}

tasks.register("run") {
    dependsOn("first", "second")
}

build.gradle

tasks.register("first") {
    doLast {
        throw new GradleException("First task failing as expected")
    }
}

tasks.register("second") {
    doLast {
        logger.lifecycle("Second task succeeding as expected")
    }
}

tasks.register("run") {
    dependsOn("first", "second")
}

This build is run with gradle run -Dorg.gradle.continue=true, so that the failure of the first task does not prevent the second task from executing.

This relies on person running the build to remember to set this property, which is error prone and not portable across different machines and environments.

Do This Instead

├── build.gradle.kts
└── gradle.properties
└── settings.gradle.kts

├── build.gradle
└── gradle.properties
└── settings.gradle

gradle.properties

org.gradle.continue=true

This build sets the org.gradle.continue property in the gradle.properties file.

Now it can be executed using only gradle run, and the continue property will always be set automatically across all environments.

References

Gradle properties

Tags

#properties

Name Your Root Project

Always name your root project in the settings.gradle(.kts) file.

Explanation

While an empty settings.gradle(.kts) file is enough to create a multi-project build, you should always set the rootProject.name property.

By default, the root project’s name is taken from the directory containing the build. This can be problematic if the directory name contains spaces, Gradle logical path separators, or other special characters. It also makes task paths dependent on the directory name, rather than being reliably defined.

Explicitly setting the root project’s name ensures consistency across environments. Project names appear in error messages, logs, and reports, and builds often run on different machines, such as CI servers. Builds may execute on a variety of machines or environments, such as CI servers, and should report the same root project name anywhere to make the project more comprehensible.

Example

Don’t Do This

settings.gradle.kts

// Left empty

settings.gradle

// Left empty

In this build, the settings file is empty and the root project has no explicit name. Running the projects report shows that Gradle assigns an implicit name to the root project, derived from the build’s current directory.

Unfortunately that name varies based on where the project currently lives. For example, if the project is checked out into a directory named some-directory-name, the output of ./gradlew projects will look like this:

> Task :projects

Projects:

------------------------------------------------------------
Root project 'some-directory-name'
------------------------------------------------------------

Do This Instead

settings.gradle.kts

rootProject.name = "my-example-project"

settings.gradle

rootProject.name = "my-example-project"

In this build, the root project is explicitly named. The explicit name my-example-project will be used in all reports, logs, and error messages. Regardless of where the project lives, the output of ./gradlew projects will look like this:

nameYourRootProject-do.out

> Task :projects

Projects:

------------------------------------------------------------
Root project 'my-example-project'
------------------------------------------------------------

Project hierarchy:

Root project 'my-example-project'
No sub-projects

To see a list of the tasks of a project, run gradle <project-path>:tasks
For example, try running gradle :tasks

BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed

References

Naming recommendations

Tags

#settings

Do not use `gradle.properties` in subprojects

Do not place a gradle.properties file inside subprojects to configure your build.

Explanation

Gradle allows gradle.properties files in both the root project and subprojects, but support for subproject properties is inconsistent. Gradle itself and many popular plugins (such as the Android Gradle Plugin and Kotlin Gradle Plugin) do not reliably handle this pattern.

Using subproject gradle.properties files also makes it harder to understand and debug your build. Property values may be scattered across multiple locations, overridden in unexpected ways, or difficult to trace back to their source.

If you need to set properties for a single subproject, define them directly in that subproject’s build.gradle(.kts). If you need to apply properties across multiple subprojects, extract the configuration into a convention plugin.

Example

Don’t Do This

├── app
│   ├── ⋮
│   ├── build.gradle.kts
│   └── gradle.properties
├── utilities
│   ├── ⋮
│   ├── build.gradle.kts
│   └── gradle.properties
└── settings.gradle.kts

├── app
│   ├── ⋮
│   ├── build.gradle
│   └── gradle.properties
├── utilities
│   ├── ⋮
│   ├── build.gradle
│   └── gradle.properties
└── settings.gradle

gradle.properties

# This file is located in /app
propertyA=fixedValue
propertyB=someValue

build.gradle.kts

// This file is located in /app
tasks.register("printProperties") { // (1)
    val propA = project.findProperty("propertyA") // (2)
    val propB = project.findProperty("propertyB")

    doLast {
        println("propertyA in app: $propA")
        println("propertyB in app: $propB")
    }
}

build.gradle

// This file is located in /app
tasks.register("printProperties") { // (1)
    def propA = project.findProperty("propertyA") // (2)
    def propB = project.findProperty("propertyB")

    doLast {
        println "propertyA in app: $propA"
        println "propertyB in app: $propB"
    }
}

gradle.properties

# This file is located in /util
propertyA=fixedValue
propertyB=otherValue

build.gradle.kts

// This file is located in /util
tasks.register("printProperties") {
    val propA = project.findProperty("propertyA")
    val propB = project.findProperty("propertyB") // (3)

    doLast {
        println("propertyA in util: $propA")
        println("propertyB in util: $propB")
    }
}

build.gradle

// This file is located in /util
tasks.register("printProperties") {
    def propA = project.findProperty("propertyA")
    def propB = project.findProperty("propertyB") // (3)

    doLast {
        println "propertyA in util: $propA"
        println "propertyB in util: $propB"
    }
}

Register a task that uses the value of properties in each subproject.
The task reads properties, which are supplied by the project-local app/gradle.properties file. propertyA does not vary between subprojects.
'util’s print task reads the properties which are supplied by util/gradle.properties. propertyB varies between subprojects.

This structure requires duplicating properties that are shared between subprojects and is not guaranteed to remain supported.

Do This Instead

├── buildSrc
│   └──  ⋮
├── app
│   ├── ⋮
│   └── build.gradle.kts
├── utilities
│   ├── ⋮
│   └── build.gradle.kts
├── settings.gradle.kts
└── gradle.properties

├── buildSrc
│   └──  ⋮
├── app
│   ├── ⋮
│   └──  build.gradle
├── utilities
│   ├── ⋮
│   └── build.gradle
├── settings.gradle
└── gradle.properties

gradle.properties

# This file is located in the root of the build
propertyA=fixedValue
propertyB=someValue

ProjectProperties.kt

import org.gradle.api.provider.Property

interface ProjectProperties { // (1)
    val propertyA: Property<String>
    val propertyB: Property<String>
}

ProjectProperties.groovy

import org.gradle.api.provider.Property

interface ProjectProperties { // (1)
    Property<String> getPropertyA()
    Property<String> getPropertyB()
}

project-properties.gradle.kts

extensions.create<ProjectProperties>("myProperties") // (2)

tasks.register("printProperties") { // (3)
    val myProperties = project.extensions.getByName("myProperties") as ProjectProperties
    val projectName = project.name

    doLast {
        println("propertyA in ${projectName}: ${myProperties.propertyA.get()}")
        println("propertyB in ${projectName}: ${myProperties.propertyB.get()}")
    }
}

project-properties.gradle

extensions.create("myProperties", ProjectProperties) // (2)

tasks.register("printProperties") { // (3)
    def myProperties = project.extensions.getByName("myProperties") as ProjectProperties
    def projectName = project.name

    doLast {
        println("propertyA in ${projectName}: ${myProperties.propertyA.get()}")
        println("propertyB in ${projectName}: ${myProperties.propertyB.get()}")
    }
}

build.gradle.kts

// This file is located in /app
plugins { // (4)
    id("project-properties")
}

myProperties { // (5)
    propertyA = providers.gradleProperty("propertyA")
    propertyB = providers.gradleProperty("propertyB")
}

build.gradle

// This file is located in /app
plugins { // (4)
    id "project-properties"
}

myProperties { // (5)
    propertyA = providers.gradleProperty("propertyA")
    propertyB = providers.gradleProperty("propertyB")
}

build.gradle.kts

// This file is located in /util
plugins {
    id("project-properties")
}

myProperties {
    propertyA = providers.gradleProperty("propertyA")
    propertyB = "otherValue" // (6)
}

build.gradle

// This file is located in /util
plugins {
    id "project-properties"
}

myProperties {
    propertyA = providers.gradleProperty("propertyA")
    propertyB = "otherValue" // (6)
}

Define a simple extension type in buildSrc to hold property values.
Register that property in a convention plugin.
Register tasks using property values in the convention plugin.
Apply the convention plugin in each subproject.
Set the extension’s property values in each subproject’s build script. This uses the values defined in the root gradle.properties file. The task reads values from the extension, not directly from the project properties.
When values need to vary between subprojects, they can be set directly on the extension.

This structure uses an extension type to hold values, allowing properties to be strongly typed, and for property values and operations on properties to be defined in a single location. Overriding values per subproject remains straightforward.

References

Gradle properties

Tags

#properties

Avoid `afterEvaluate`

Do not use project.afterEvaluate {} to configure tasks, wire properties, or react to plugin application. Use lazy properties and pluginManager.withPlugin() instead.

Explanation

afterEvaluate registers a callback that runs after Gradle finishes evaluating and configuring a project. It was historically used to "delay" reading a value until configuration was complete — for example, reading an extension property that users set at the bottom of their build script, or checking whether another plugin was applied.

This pattern is outdated, and problematic for several reasons:

Ordering is fragile. Multiple afterEvaluate callbacks execute in registration order. If two plugins or scripts both use afterEvaluate, one may see stale or incomplete configuration depending on which was registered first. This creates subtle bugs that are extremely difficult to diagnose.
It defeats task configuration avoidance. Tasks registered or configured inside afterEvaluate are touched eagerly during configuration, even if they will never execute. This may cause unnecessary work and slow down the configuration phase of the build.
It is incompatible with the Configuration Cache. afterEvaluate callbacks capture mutable project state that cannot be serialized reliably.

Gradle’s lazy Property and Provider types solve the same underlying problem — deferring value resolution — without any of these drawbacks. A Property<T> can be wired at configuration time but its value is resolved only when needed, typically during task execution. This makes configuration order-independent and fully compatible with the configuration cache.

Similarly, pluginManager.withPlugin() reacts to plugin application safely and immediately, regardless of when the plugin is actually applied — no callback ordering to worry about.

When `afterEvaluate` may still be appropriate

There are narrow use cases where afterEvaluate remains the only available hook:

Fail-fast validation — verifying that required project configuration has been set and failing the build early with a clear error message.
Logging or reporting — printing diagnostic information about the project’s final configuration state.

Even in these cases, exercise caution: your afterEvaluate must be the last (or only) one registered to see the final configuration state. If another plugin registers an afterEvaluate after yours, your callback may see incomplete configuration.

If you find yourself reaching for afterEvaluate because Gradle’s lazy APIs do not cover your use case, consider filing a bug. afterEvaluate should be a last resort, not a first choice.

Example

Given the following project layout:

.
├── build.gradle.kts
├── buildSrc/
│   ├── build.gradle.kts
│   └── src/main/kotlin/
│       └── AppInfoPlugin.kt
└── settings.gradle.kts

.
├── build.gradle
├── buildSrc/
│   ├── build.gradle
│   └── src/main/groovy/
│       └── AppInfoPlugin.groovy
└── settings.gradle

Don’t Do This

The plugin uses afterEvaluate to delay reading the extension value and to check whether java-library was applied:

buildSrc/src/main/kotlin/AppInfoPlugin.kt

interface AppInfoExtension {
    val appName: Property<String>
}

class AppInfoPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        val extension = project.extensions.create("appInfo", AppInfoExtension::class.java)

        project.afterEvaluate { // (1)
            val name = extension.appName.getOrElse("unnamed") // (2)

            tasks.register("printAppInfo") { // (3)
                doLast {
                    println("App: $name")
                }
            }

            if (plugins.hasPlugin("java-library")) { // (4)
                tasks.named("printAppInfo") {
                    doLast {
                        println("Jar: $name.jar")
                    }
                }
                tasks.named("jar", Jar::class.java) {
                    archiveBaseName.set(name)
                }
            }
        }
    }
}

buildSrc/src/main/groovy/AppInfoPlugin.groovy

interface AppInfoExtension {
    Property<String> getAppName()
}

class AppInfoPlugin implements Plugin<Project> {
    void apply(Project project) {
        def extension = project.extensions.create("appInfo", AppInfoExtension)

        project.afterEvaluate { // (1)
            def name = extension.appName.getOrElse("unnamed") // (2)

            project.tasks.register("printAppInfo") { // (3)
                doLast {
                    println "App: $name"
                }
            }

            if (project.plugins.hasPlugin("java-library")) { // (4)
                project.tasks.named("printAppInfo") {
                    doLast {
                        println "Jar: ${name}.jar"
                    }
                }
                project.tasks.named("jar", Jar) {
                    archiveBaseName.set(name)
                }
            }
        }
    }
}

The plugin’s afterEvaluate runs before any afterEvaluate registered later in the build script — ordering depends on registration order.
getOrElse reads the property’s current value immediately. If the value is set in a later afterEvaluate, this will never see it.
Registering a task inside afterEvaluate defeats task configuration avoidance.
Checking plugin presence inside afterEvaluate assumes all plugins have been applied before this callback runs.

The build script applies the plugin and sets the extension value in its own afterEvaluate:

build.gradle.kts

plugins {
    id("java-library")
    id("app-info-plugin")
}

afterEvaluate {
    the<AppInfoExtension>().appName.set("my-app") // (1)
}

build.gradle

plugins {
    id 'java-library'
    id 'app-info-plugin'
}

afterEvaluate {
    appInfo { // (1)
        appName.set('my-app')
    }
}

This afterEvaluate runs after the plugin’s — by the time it sets the name, the plugin has already captured the default value.

Running printAppInfo outputs unnamed — not my-app as the user intended:

> Task :printAppInfo
App: unnamed
Jar: unnamed.jar

BUILD SUCCESSFUL in 0s
5 actionable tasks: 5 executed

The plugin’s afterEvaluate callback was registered first (during Plugin.apply()) and ran first, reading the property before the build script’s afterEvaluate had a chance to set it.

Do This Instead

The proper way to write this plugin uses lazy Property types and pluginManager.withPlugin():

buildSrc/src/main/kotlin/AppInfoPlugin.kt

interface AppInfoExtension {
    val appName: Property<String>
}

class AppInfoPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        val extension = project.extensions.create("appInfo", AppInfoExtension::class.java)
        extension.appName.convention("unnamed") // (1)

        project.tasks.register("printAppInfo") {
            val name = extension.appName
            doLast {
                println("App: ${name.get()}") // (2)
            }
        }

        project.pluginManager.withPlugin("java-library") { // (3)
            project.tasks.named("printAppInfo") {
                val jarName = extension.appName
                doLast {
                    println("Jar: ${jarName.get()}.jar")
                }
            }
            project.tasks.named("jar", Jar::class.java) {
                archiveBaseName.set(extension.appName)
            }
        }
    }
}

buildSrc/src/main/groovy/AppInfoPlugin.groovy

interface AppInfoExtension {
    Property<String> getAppName()
}

class AppInfoPlugin implements Plugin<Project> {
    void apply(Project project) {
        def extension = project.extensions.create("appInfo", AppInfoExtension)
        extension.appName.convention("unnamed") // (1)

        project.tasks.register("printAppInfo") {
            def name = extension.appName
            doLast {
                println "App: ${name.get()}" // (2)
            }
        }

        project.pluginManager.withPlugin("java-library") { // (3)
            project.tasks.named("printAppInfo") {
                def jarName = extension.appName
                doLast {
                    println "Jar: ${jarName.get()}.jar"
                }
            }
            project.tasks.named("jar", Jar) {
                archiveBaseName.set(extension.appName)
            }
        }
    }
}

convention() provides a default value that is used only if no explicit value is set via set().
The value is resolved at execution time via get() — configuration order does not matter.
pluginManager.withPlugin() fires when the plugin is applied, regardless of order. If the plugin is never applied, the callback is never invoked.

The build script is nearly identical — the change is in the plugin, not the consumer:

build.gradle.kts

plugins {
    id("java-library")
    id("app-info-plugin")
}

appInfo {
    appName.set("my-app") // (1)
}

build.gradle

plugins {
    id 'java-library'
    id 'app-info-plugin'
}

appInfo {
    appName.set('my-app') // (1)
}

The value is set during normal configuration. Because the plugin wires the Property lazily, it is only read at execution time.

Running printAppInfo now correctly outputs my-app:

$ gradlew printAppInfo
> Task :printAppInfo
App: my-app
Jar: my-app.jar

BUILD SUCCESSFUL in 0s
5 actionable tasks: 5 executed

References

Tags

#task-configuration-avoidance, #plugins, #structuring-builds

Consider use of `@Incubating` APIs carefully

Use Incubating APIs deliberately and with awareness of trade-offs. New or unstable Incubating features can require updates even on minor Gradle upgrades, while some features are close to Stable and already widely adopted. Weigh the benefits against the likely increase in maintenance effort.

Explanation

Compared to many other ecosystems, Gradle is very strict with Incubating features. As long as there are outstanding issues related to the feature, it will not be promoted to the Stable state. An Incubating state means that breaking changes can happen in non-major releases. However, the closer the feature is to being Stable, the less likely it is to change. There are a number of features that are already widely adopted and recommended as best practices, even though they are still incubating, like dependencyResolutionManagement.repositories.

When considering using an Incubating feature, the best approach is to check its maturity and stability:

Check which Gradle version introduced it.
Check related GitHub issues, how many are linked, and whether any would affect you.

If the feature is new or still has many linked issues, consider its use carefully. It may introduce an additional maintenance cost for your build setup, as you may need to update your build scripts even on minor version updates.

Note	Remember that the goal of Incubating features is to put them in users' hands early to gather feedback and guide their evolution. If you are using such features, please provide feedback and report bugs if you encounter any.

References

Tags

#upgrades

Best Practices for Structuring Builds

Modularize Your Builds

Modularize your builds by splitting your code into multiple projects.

Explanation

Splitting your build’s source into multiple Gradle projects (modules) is essential for leveraging Gradle’s automatic work avoidance and parallelization features. When a source file changes, Gradle only recompiles the affected projects. If all your sources reside in a single project, Gradle can’t avoid recompilation and won’t be able to run tasks in parallel. Splitting your source into multiple projects can provide additional performance benefits by minimizing each subproject’s compilation classpath and ensuring code generating tools such as annotation and symbol processors run only on the relevant files.

Do this soon. Don’t wait until you hit some arbitrary number of source files or classes to do this, instead structure your build into multiple projects from the start using whatever natural boundaries exist in your codebase.

Exactly how to best split your source varies with every build, as it depends on the particulars of that build. Here are some common patterns we found that can work well and make cohesive projects:

API vs. Implementation
Front-end vs. Back-end
Core business logic vs. UI
Vertical slices (e.g., feature modules each containing UI + business logic)
Inputs to source generation vs. their consumers
Or simply closely related classes.

Ultimately, the specific scheme matters less than ensuring that your build is split logically and consistently.

Expanding a build to hundreds of projects is common, and Gradle is designed to scale to this size and beyond. In the extreme, tiny projects containing only a class or two are probably counterproductive. However, you should typically err on the side of adding more projects rather than fewer.

Example

Don’t Do This

A common way to structure new builds

├── app // This project contains a mix of classes
│    ├── build.gradle.kts
│    └── src
│        └── main
│            └── java
│                └── org
│                    └── example
│                        └── CommonsUtil.java
│                        └── GuavaUtil.java
│                        └── Main.java
│                        └── Util.java
├── settings.gradle.kts

A common way to structure new builds

├── app // This project contains a mix of classes
│    ├── build.gradle
│    └── src
│        └── main
│            └── java
│                └── org
│                    └── example
│                        └── CommonsUtil.java
│                        └── GuavaUtil.java
│                        └── Main.java
│                        └── Util.java
├── settings.gradle

settings.gradle.kts

include("app") // (1)

settings.gradle

include("app") // (1)

build.gradle.kts

plugins {
    application // (2)
}

dependencies {
    implementation("com.google.guava:guava:31.1-jre") // (3)
    implementation("commons-lang:commons-lang:2.6")
}

application {
    mainClass = "org.example.Main"
}

build.gradle

plugins {
    id 'application' // (2)
}

dependencies {
    implementation 'com.google.guava:guava:31.1-jre' // (3)
    implementation 'commons-lang:commons-lang:2.6'
}

application {
    mainClass = "org.example.Main"
}

This build contains only a single project (in addition to the root project) that contains all the source code. If there is any change to any source file, Gradle will have to recompile and rebuild everything. While incremental compilation will help (especially in this simplified example) this is still less efficient then avoidance. Gradle also won’t be able to run any tasks in parallel, since all these tasks are in the same project, so this design won’t scale nicely.
As there is only a single project in this build, the application plugin must be applied here. This means that the application plugin will affect all source files in the build, even those which have no need for it.
Likewise, the dependencies here are only needed by each particular implmentation of util. There’s no need for the implementation using Guava to have access to the Commons library, but it does because they are all in the same project. This also means that the classpath for each subproject is much larger than it needs to be, which can lead to longer build times and other confusion.

Do This Instead

A better way to structure this build

├── app
│    ├── build.gradle.kts
│    └── src
│        └── main
│            └── java
│                └── org
│                    └── example
│                        └── Main.java
├── settings.gradle.kts
├── util
│    ├── build.gradle.kts
│    └── src
│        └── main
│            └── java
│                └── org
│                    └── example
│                        └── Util.java
├── util-commons
│    ├── build.gradle.kts
│    └── src
│        └── main
│            └── java
│                └── org
│                    └── example
│                        └── CommonsUtil.java
└── util-guava
    ├── build.gradle.kts
    └── src
        └── main
            └── java
                └── org
                    └── example
                        └── GuavaUtil.java

A better way to structure this build

├── app // App contains only the core application logic
│    ├── build.gradle
│    └── src
│        └── main
│            └── java
│                └── org
│                    └── example
│                        └── Main.java
├── settings.gradle
├── util // Util contains only the core utility logic
│    ├── build.gradle
│    └── src
│        └── main
│            └── java
│                └── org
│                    └── example
│                        └── Util.java
├── util-commons // One particular implementation of util, using Apache Commons
│    ├── build.gradle
│    └── src
│        └── main
│            └── java
│                └── org
│                    └── example
│                        └── CommonsUtil.java
└── util-guava // Another implementation of util, using Guava
    ├── build.gradle
    └── src
        └── main
            └── java
                └── org
                    └── example
                        └── GuavaUtil.java

settings.gradle.kts

include("app") // (1)
include("util")
include("util-commons")
include("util-guava")

settings.gradle

include("app") // (1)
include("util")
include("util-commons")
include("util-guava")

build.gradle.kts

// This is the build.gradle file for the app module

plugins {
    application // (2)
}

dependencies { // (3)
    implementation(project(":util-guava"))
    implementation(project(":util-commons"))
}

application {
    mainClass = "org.example.Main"
}

build.gradle

// This is the build.gradle file for the app module

plugins {
    id "application" // (2)
}

dependencies { // (3)
    implementation project(":util-guava")
    implementation project(":util-commons")
}

application {
    mainClass = "org.example.Main"
}

build.gradle.kts

// This is the build.gradle file for the util-commons module

plugins { // (4)
    `java-library`
}

dependencies { // (5)
    api(project(":util"))
    implementation("commons-lang:commons-lang:2.6")
}

build.gradle

// This is the build.gradle file for the util-commons module

plugins { // (4)
    id "java-library"
}

dependencies { // (5)
    api project(":util")
    implementation "commons-lang:commons-lang:2.6"
}

build.gradle.kts

// This is the build.gradle file for the util-guava module

plugins {
    `java-library`
}

dependencies {
    api(project(":util"))
    implementation("com.google.guava:guava:31.1-jre")
}

build.gradle

// This is the build.gradle file for the util-guava module

plugins {
    id "java-library"
}

dependencies {
    api project(":util")
    implementation "com.google.guava:guava:31.1-jre"
}

This build logically splits the source into multiple projects. Each project can be built independently, and Gradle can run tasks in parallel. This means that if you change a single source file in one of the projects, Gradle will only need to recompile and rebuild that project, not the entire build.
The application plugin is only applied to the app project, which is the only project that needs it.
Each project only adds the dependencies it needs. This means that the classpath for each subproject is much smaller, which can lead to faster build times and less confusion.
Each project only adds the specific plugins it needs.
Each project only adds the dependencies it needs. Projects can effectively use API vs. Implementation separation.

References

Tags

Do Not Put Source Files in the Root Project

Do not put source files in your root project; instead, put them in a separate project.

Explanation

The root project is a special Project in Gradle that serves as the entry point for your build.

It is the place to configure some settings and conventions that apply globally to the entire build, that are not configured via Settings. For example, you can declare (but not apply) plugins here to ensure the same plugin version is consistently available across all projects and define other configurations shared by all projects within the build.

Note	Be careful not to apply plugins unnecessarily in the root project - many plugins only affect source code and should only be applied to the projects that contain source code.

The root project should not be used for source files, instead they should be located in a separate Gradle project.

Setting up your build like this from the start will also make it easier to add new projects as your build grows in the future.

Example

Don’t Do This

A common way to structure new builds

├── build.gradle.kts // Applies the `java-library` plugin to the root project
├── settings.gradle.kts
└── src // This directory shouldn't exist
    └── main
        └── java
            └── org
                └── example
                    └── MyClass1.java

A common way to structure new builds

├── build.gradle // Applies the `java-library` plugin to the root project
├── settings.gradle
└── src // This directory shouldn't exist
    └── main
        └── java
            └── org
                └── example
                    └── MyClass1.java

build.gradle.kts

plugins { // (1)
    `java-library`
}

build.gradle

plugins {
    id 'java-library' // (1)
}

The java-library plugin is applied to the root project, as there are Java source files are in the root project.

Do This Instead

A better way to structure new builds

├── core
│    ├── build.gradle.kts // Applies the `java-library` plugin to only the `core` project
│    └── src // Source lives in a "core" (sub)project
│        └── main
│            └── java
│                └── org
│                    └── example
│                        └── MyClass1.java
└── settings.gradle.kts

A better way to structure new builds

├── core
│    ├── build.gradle // Applies the `java-library` plugin to only the `core` project
│    └── src // Source lives in a "core" (sub)project
│        └── main
│            └── java
│                └── org
│                    └── example
│                        └── MyClass1.java
└── settings.gradle

settings.gradle.kts

include("core") // (1)

settings.gradle

include("core") // (1)

build.gradle.kts

// This is the build.gradle.kts file for the core module

plugins { // (2)
    `java-library`
}

build.gradle

// This is the build.gradle file for the core module

plugins { // (2)
    id 'java-library'
}

The root project exists only to configure the build, informing Gradle of a (sub)project named core.
The java-library plugin is only applied to the core project, which contains the Java source files.

References

Tags

Favor `build-logic` Composite Builds for Build Logic

You should set up a Composite Build (often called an "included build") to hold your build logic—including any custom plugins, convention plugins, and other build-specific customizations.

Explanation

The preferred location for build logic is an included build (typically named build-logic), not in buildSrc.

The automatically available buildSrc is great for rapid prototyping, but it comes with some subtle disadvantages:

There are classloader differences in how these 2 approaches behave that can be surprising; included builds are treated just like external dependencies, which is a simpler mental model. Dependency resolution behaves subtly differently in buildSrc.
There can potentially be fewer task invalidations in a build when files in an included build are modified, leading to faster builds. Any change in buildSrc causes the entire build to become out-of-date, whereas changes in a subproject of an included build only cause projects in the build using the products of that particular subproject to be out-of-date.
Included builds are complete Gradle builds and can be opened, worked on, and built independently as standalone projects. It is straightforward to publish their products, including plugins, in order to share them with other projects.
The buildSrc project automatically applies the java plugin, which may be unnecessary.

One important caveat to this recommendation is when creating Settings plugins. Defining these in a build-logic project requires it to be included in the pluginManagement block of the main build’s settings.gradle(.kts) file, in order to make these plugins available to the build early enough to be applied to the Settings instance. This is possible, but reduces Build Caching capability, potentially impacting performance. A better solution is to use a separate, minimal, included build (e.g. build-logic-settings) to hold only Settings plugins.

Another potential reason to use buildSrc is if you have a very large number of subprojects within your included build-logic. Applying a different set of build-logic plugins to the subprojects in your including build will result in a different classpath being used for each. This may have performance implications and make your build harder to understand. Using different plugin combinations can cause features like Build Services to break in difficult to diagnose ways.

Ideally, there would be no difference between using buildSrc and an included build, as buildSrc is intended to behave like an implicitly available included build. However, due to historical reasons, these subtle differences still exist. As this changes, this recommendation may be revised in the future. For now, these differences can introduce confusion.

Since setting up a composite build requires only minimal additional configuration, we recommend using it over buildSrc in most cases, especially for creating convention plugins.

Example

Don’t Do This

├── build.gradle.kts
├── buildSrc
│    ├── build.gradle.kts
│    └── src
│        └── main
│            └── java
│                └── org
│                    └── example
│                        ├── MyPlugin.java
│                        └── MyTask.java
└── settings.gradle.kts

├── build.gradle
├── buildSrc
│    ├── build.gradle
│    └── src
│        └── main
│            └── java
│                └── org
│                    └── example
│                        ├── MyPlugin.java
│                        └── MyTask.java
└── settings.gradle

build.gradle.kts

// This file is located in /buildSrc

plugins {
    `java-gradle-plugin`
}

gradlePlugin {
    plugins {
        create("myPlugin") {
            id = "org.example.myplugin"
            implementationClass = "org.example.MyPlugin"
        }
    }
}

build.gradle

// This file is located in /buildSrc

plugins {
    id "java-gradle-plugin"
}

gradlePlugin {
    plugins {
        create("myPlugin") {
            id = "org.example.myplugin"
            implementationClass = "org.example.MyPlugin"
        }
    }
}

Set up a Plugin Build: This is the same using either method.

settings.gradle.kts

rootProject.name = "favor-composite-builds"

settings.gradle

rootProject.name = "favor-composite-builds"

buildSrc products are automatically usable: There is no additional configuration with this method.

Do This Instead

├── build-logic
│    ├── plugin
│    │    ├── build.gradle.kts
│    │    └── src
│    │        └── main
│    │            └── java
│    │                └── org
│    │                    └── example
│    │                        ├── MyPlugin.java
│    │                        └── MyTask.java
│    └── settings.gradle.kts
├── build.gradle.kts
└── settings.gradle.kts

├── build-logic
│    ├── plugin
│    │    ├── build.gradle
│    │    └── src
│    │        └── main
│    │            └── java
│    │                └── org
│    │                    └── example
│    │                        ├── MyPlugin.java
│    │                        └── MyTask.java
│    └── settings.gradle
├── build.gradle
└── settings.gradle

build.gradle.kts

// This file is located in /build-logic/plugin

plugins {
    `java-gradle-plugin`
}

gradlePlugin {
    plugins {
        create("myPlugin") {
            id = "org.example.myplugin"
            implementationClass = "org.example.MyPlugin"
        }
    }
}

build.gradle

// This file is located in /build-logic/plugin

plugins {
    id "java-gradle-plugin"
}

gradlePlugin {
    plugins {
        create("myPlugin") {
            id = "org.example.myplugin"
            implementationClass = "org.example.MyPlugin"
        }
    }
}

Set up a Plugin Build: This is the same using either method.

settings.gradle.kts

// This file is located in the root project

includeBuild("build-logic") // (1)

rootProject.name = "favor-composite-builds"

settings.gradle

// This file is located in the root project

includeBuild("build-logic") // (1)

rootProject.name = "favor-composite-builds"

settings.gradle.kts

// This file is located in /build-logic

rootProject.name = "build-logic"

include("plugin") // (2)

settings.gradle

// This file is located in /build-logic

rootProject.name = "build-logic"

include("plugin") // (2)

Composite builds must be explicitly included: Use the includeBuild method to locate and include a build in order to use its products.
Structure your included build into subprojects: This allows the main build to only depend on the necessary parts of the included build.

References

Tags

#structuring-builds, #composite-builds

Avoid Unintentionally Creating Empty Projects

When using a hierarchical directory structure to organize your Gradle projects, make sure to avoid unintentionally creating empty projects in your build.

Explanation

When you use the Settings.include() method to include a project in your Grade settings file, you typically include projects by supplying the directory name like include("featureA"). This usage assumes that featureA is located at the root of your build.

You can include projects located in nested subdirectories by specifying their full project path using : as a separator between path segments. For instance, if project search was located in a subdirectory named features, itself located in a subdirectory named subs, you could call include(":subs:features:search") to include it.

Nesting projects in a sensible hierarchical directory structure is common practice in larger Gradle builds. This approach helps organize large builds and improves comprehensibility, compared to placing all projects directly under the build’s root.

However, without further configuration, Gradle will create empty projects for each element in every hierarchical path, even if some of those directories do not contain actual Gradle projects. In the example above, Gradle will create a project named :subs, a project named :subs:features, and a project named :subs:features:search. This behavior is usually not intended, as you likely only want to include the search project.

Unused projects - even if empty - can surprise maintainers, clutter reports, and make your build harder to understand. They also introduce unintended side effects. If you use allprojects { … } or subprojects { … }, plugins and configuration blocks will apply to every project, including the empty ones. This can degrade build performance. Additionally, invoking tasks on deeply nested projects requires using the full project path, such as gradle :subs:features:search:build, instead of the shorter gradle :search:build.

To avoid these downsides when using a hierarchical project structure, you can provide a flat name when including the project and explicitly set the Project.projectDir property for any projects located in nested directories:

include(':my-web-module')
project(':my-web-module').projectDir = file("subs/web/my-web-module")

This will prevent Gradle from creating empty projects for each element of the project’s path.

Note

Always use an identical logical project name and physical project location to avoid confusion. Don’t include a project named :search and locate it at features/ui/default-search-toolbar, as this will lead to confusion about the location of the project. Instead, locate this project at features/ui/search.

You should avoid unnecessarily deep directory structures. For builds containing only a few projects, it’s usually better to keep the structure flat by placing all projects at the root of the build. This eliminates the need to explicitly set projectDir. Within the context of a particular build, the pathless project name should clearly indicate where the project is located. You can also run the projects report for more information about the projects in your build and their locations.

If you find yourself facing ambiguity about project locations, consider simplifying the directory layout by flattening the structure, or using longer, more descriptive project names.

Example

Don’t Do This

├── settings.gradle.kts
├── app/ // (1)
│   ├── build.gradle.kts
│   └── src/
└── subs/ // (2)
    └── web/ // (3)
        ├── my-web-module/ // (4)
            ├── src/
            └── build.gradle.kts

├── settings.gradle
├── app/ // (1)
│   ├── build.gradle
│   └── src/
└── subs/ // (2)
    └── web/ // (3)
        ├── my-web-module/ // (4)
            ├── src/
            └── build.gradle

A project named app located at the root of the build
A directory named subs that is not intended to represent a Gradle project, but is used to organize the build
Another organizational directory not intended to represent a Gradle project
A Gradle project named my-web-module that should be included in the build

settings.gradle.kts

include(":app") // (1)
include(":subs:web:my-web-module") // (2)

settings.gradle

include(":app") // (1)
include(":subs:web:my-web-module") // (2)

Including the app project located at the root of the build requires no additional configuration
Including a project named :subs:my-web-module located in a nested subdirectory causes Gradle to create empty projects for each element of the path

avoidEmptyProjects-avoid.out

> Task :projects

Projects:

------------------------------------------------------------
Root project 'avoidEmptyProjects-avoid'
------------------------------------------------------------

Location: /home/user/gradle/samples

Project hierarchy:

Root project 'avoidEmptyProjects-avoid'
+--- Project ':app'
\--- Project ':subs'
     \--- Project ':subs:web'
          \--- Project ':subs:web:my-web-module'

Project locations:

project ':app' - /app
project ':subs' - /subs
project ':subs:web' - /subs/web
project ':subs:web:my-web-module' - /subs/web/my-web-module

To see a list of the tasks of a project, run gradle <project-path>:tasks
For example, try running gradle :app:tasks

BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed

The output of running the projects report on the above build shows that Gradle created empty projects for :subs and :subs:web.

Do This Instead

settings.gradle.kts

include(":app")

include(":my-web-module")
project(":my-web-module").projectDir = file("subs/web/my-web-module") // (1)

settings.gradle

include(":app")

include(":my-web-module")
project(":my-web-module").projectDir = file("subs/web/my-web-module") // (1)

After including the :subs:web:my-web-module project, its projectDir property is set to the physical location of the project

avoidEmptyProjects-do.out

> Task :projects

Projects:

------------------------------------------------------------
Root project 'avoidEmptyProjects-do'
------------------------------------------------------------

Location: /home/user/gradle/samples

Project hierarchy:

Root project 'avoidEmptyProjects-do'
+--- Project ':app'
\--- Project ':my-web-module'

Project locations:

project ':app' - /app
project ':my-web-module' - /subs/web/my-web-module

To see a list of the tasks of a project, run gradle <project-path>:tasks
For example, try running gradle :app:tasks

BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed

The output of running the projects report on the above build shows that now Gradle only creates the intended projects for this build.

You can also now invoke tasks on the my-web-module project using the shorter name :my-web-module like gradle :my-web-module:build, instead of gradle :subs:web:my-web-module:build.

References

Multi-Project Builds

Tags

Use Convention Plugins for Common Build Logic

Use convention plugins to encapsulate and reuse shared build logic across multiple projects in your build.

Explanation

Instead of duplicating configuration across multiple build scripts, you can easily move common logic into a reusable convention plugins.

This approach offers several benefits:

Reduces duplication: Shared build logic lives in one place, making your build easier to understand.
Unlocks modularization: Convention plugins can apply other convention plugins, allowing you to orchestrate your build logic from small pieces.
Centralizes configuration: Updates to build behavior can be made in one file instead of many.
Keeps build files clean: Project build files stay focused on project-specific configuration.
Improves IDE support: IDEs can better understand and validate build logic when it is structured in plugins.

Convention plugins are quicker to create than typed binary plugins extending the Plugin class. They are often a better choice for build logic that does not need to be shared outside a build, and that is simple enough to not require additional type safeness and testability benefits. Unlike binary plugins, convention plugins allow accessing plugin extensions, tasks and configurations via static accessors in build scripts written in Kotlin.

While setting up convention plugins takes some initial effort, it pays off by simplifying maintenance, improving comprehensibility, and making it easier to add new projects as your codebase grows.

As mentioned in Favor build-logic Composite Builds for Build Logic, we recommend placing your convention plugins in an included build (often named build-logic) instead of buildSrc.

Example

Don’t Do This

project-a/build.gradle.kts

plugins {
    `java-library`
}

// Duplicated configuration across multiple build files
java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

tasks.withType<JavaCompile>().configureEach {
    options.encoding = "UTF-8"
    options.compilerArgs.addAll(listOf("-Xlint:unchecked", "-Xlint:deprecation")) // (1)
}

tasks.test {
    useJUnitPlatform()
    maxParallelForks = (Runtime.getRuntime().availableProcessors() / 2).takeIf { it > 0 } ?: 1 // (2)
}

dependencies {
    testImplementation("org.junit.jupiter:junit-jupiter:5.9.3") // (3)
}

project-b/build.gradle.kts

plugins {
    `java-library`
}

// Duplicated configuration across multiple build files
java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

tasks.withType<JavaCompile>().configureEach {
    options.encoding = "UTF-8"
    options.compilerArgs.addAll(listOf("-Xlint:unchecked", "-Xlint:deprecation")) // (1)
}

tasks.test {
    useJUnitPlatform()
    maxParallelForks = (Runtime.getRuntime().availableProcessors() / 2).takeIf { it > 0 } ?: 1 // (2)
}

dependencies {
    testImplementation("org.junit.jupiter:junit-jupiter:5.9.3") // (3)
    api("com.google.guava:guava:23.0") // (4)
}

project-a/build.gradle

plugins {
    id("java-library")
}

// Duplicated configuration across multiple build files
java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

tasks.withType(JavaCompile).configureEach {
    options.encoding = "UTF-8"
    options.compilerArgs += ["-Xlint:unchecked", "-Xlint:deprecation"] // (1)
}

test {
    useJUnitPlatform()
    maxParallelForks = Runtime.runtime.availableProcessors().intdiv(2) ?: 1 // (2)
}

dependencies {
    testImplementation("org.junit.jupiter:junit-jupiter:5.9.3") // (3)
}

project-b/build.gradle

plugins {
    id("java-library")
}

// Duplicated configuration across multiple build files
java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

tasks.withType(JavaCompile).configureEach {
    options.encoding = "UTF-8"
    options.compilerArgs += ["-Xlint:unchecked", "-Xlint:deprecation"] // (1)
}

test {
    useJUnitPlatform()
    maxParallelForks = Runtime.runtime.availableProcessors().intdiv(2) ?: 1 // (2)
}

dependencies {
    testImplementation("org.junit.jupiter:junit-jupiter:5.9.3") // (3)
    api("com.google.guava:guava:23.0") // (4)
}

Common compiler settings repeated across multiple projects.
Shared test configuration that must be maintained in multiple places.
Common dependencies that could be managed centrally.
Unique project dependencies.

Do This Instead

Create included build containing convention plugins for your build in build-logic and add it to your settings file:

settings.gradle.kts

pluginManagement {
    includeBuild("build-logic") // (1)
}

build-logic/build.gradle.kts

plugins {
    `kotlin-dsl` // (2)
}

settings.gradle

pluginManagement {
    includeBuild("build-logic") // (1)
}

build-logic/build.gradle

plugins {
    id("groovy-gradle-plugin") // (2)
}

Include the build-logic build, which defines convention plugins.
Enable the use of Kotlin DSL in build-logic.

Create convention plugins for each type of project in build-logic:

build-logic/src/main/kotlin/my.base-java-library.gradle.kts

plugins {
    `java-library`
}

java { // (1)
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

tasks.withType<JavaCompile>().configureEach {
    options.encoding = "UTF-8"
    options.compilerArgs.addAll(listOf("-Xlint:unchecked", "-Xlint:deprecation"))
}

build-logic/src/main/kotlin/my.java-library.gradle.kts

plugins { // (2)
    id("my.base-java-library")
    id("my.java-use-junit5")
}

build-logic/src/main/kotlin/my.java-use-junit5.gradle.kts

plugins {
    `java-library`
}

tasks.withType<Test>().configureEach { // (3)
    useJUnitPlatform()
    maxParallelForks = (Runtime.getRuntime().availableProcessors() / 2).takeIf { it > 0 } ?: 1
}

dependencies {
    testImplementation("org.junit.jupiter:junit-jupiter:5.9.3")
}

build-logic/src/main/groovy/my.base-java-library.gradle

plugins {
    id("java-library")
}

java { // (1)
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

tasks.withType(JavaCompile).configureEach {
    options.encoding = "UTF-8"
    options.compilerArgs += ["-Xlint:unchecked", "-Xlint:deprecation"]
}

build-logic/src/main/groovy/my.java-library.gradle

plugins { // (2)
    id("my.base-java-library")
    id("my.java-use-junit5")
}

build-logic/src/main/groovy/my.java-use-junit5.gradle

plugins {
    id("java-library")
}

tasks.withType(Test).configureEach { // (3)
    useJUnitPlatform()
    maxParallelForks = Runtime.runtime.availableProcessors().intdiv(2) ?: 1
}

dependencies {
    testImplementation("org.junit.jupiter:junit-jupiter:5.9.3")
}

Default settings for a Java library plugin.
A convention plugin can apply other convention plugins.
JUnit 5 configuration moved to a convention plugin.

And apply these plugin in any build files to use the shared logic:

project-a/build.gradle.kts

plugins {
    id("my.java-library") // (6)
}

project-b/build.gradle.kts

plugins {
    id("my.java-library") // (6)
}

dependencies {
    api("com.google.guava:guava:23.0") // (7)
}

project-a/build.gradle

plugins {
    id("my.java-library") // (6)
}

project-b/build.gradle

plugins {
    id("my.java-library") // (6)
}

dependencies {
    api("com.google.guava:guava:23.0") // (7)
}

References

Tags

Best Practices for Dependencies

Use Version Catalogs to Centralize Dependency Versions

Version Catalogs provide a centralized, declarative way to manage dependency versions throughout a build.

Explanation

When you define your dependency versions in a single, shared version catalog, you reduce duplication and make upgrades easier. Instead of changing dozens of build.gradle(.kts) files, you update the version in one place. This simplifies maintenance, improves consistency, and reduces the risk of accidental version drift between modules. Consistent version declarations across projects also make it easier to reason about behavior during testing—especially in modular builds where transitive upgrades can silently change runtime behavior in later stages of the build.

However, version catalogs only influence declared versions, not resolved versions. Use them in combination with dependency locking and version alignment to enforce consistency across builds. To influence resolved versions, check out platforms.

Example

Don’t Do This

Avoid declaring versions in project.ext, constants, or local variables:

build.gradle.kts

plugins {
    id("java-library")
    id("com.github.ben-manes.versions").version("0.45.0")
}
val groovyVersion = "3.0.5"

dependencies {
    api("org.codehaus.groovy:groovy:$groovyVersion")
    api("org.codehaus.groovy:groovy-json:$groovyVersion")
    api("org.codehaus.groovy:groovy-nio:$groovyVersion")

    testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")

    implementation("org.apache.commons:commons-lang3") {
        version {
            strictly("[3.8, 4.0[")
            prefer("3.9")
        }
    }
}

build.gradle

plugins {
    id('java-library')
    id('com.github.ben-manes.versions').version('0.45.0')
}
def groovyVersion = '3.0.5'

dependencies {
    api("org.codehaus.groovy:groovy:$groovyVersion")
    api("org.codehaus.groovy:groovy-json:$groovyVersion")
    api("org.codehaus.groovy:groovy-nio:$groovyVersion")

    testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")

    implementation("org.apache.commons:commons-lang3") {
        version {
            strictly("[3.8, 4.0[")
            prefer("3.9")
        }
    }
}

Avoid misusing version catalogs for unrelated concerns:

Don’t use them to store shared strings or non-library constants
Don’t overload them with arbitrary logic or plugin-specific configuration

Do This Instead

Use a centralized libs.versions.toml file in your gradle/ directory:

gradle/libs.versions.toml

[versions]
groovy = "3.0.5"
junit-jupiter = "5.10.0"

[libraries]
groovy-core = { module = "org.codehaus.groovy:groovy", version.ref = "groovy" }
groovy-json = { module = "org.codehaus.groovy:groovy-json", version.ref = "groovy" }
groovy-nio = { module = "org.codehaus.groovy:groovy-nio", version.ref = "groovy" }
commons-lang3 = { group = "org.apache.commons", name = "commons-lang3", version = { strictly = "[3.8, 4.0[", prefer = "3.9" } }
junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit-jupiter" }

[bundles]
groovy = ["groovy-core", "groovy-json", "groovy-nio"]

[plugins]
versions = { id = "com.github.ben-manes.versions", version = "0.45.0" }

build.gradle.kts

plugins {
    id("java-library")
    alias(libs.plugins.versions)
}
dependencies {
    api(libs.bundles.groovy)
    testImplementation(libs.junit.jupiter)
    implementation(libs.commons.lang3)
}

build.gradle

plugins {
    id('java-library')
    alias(libs.plugins.versions)
}
dependencies {
    api(libs.bundles.groovy)
    testImplementation(libs.junit.jupiter)
    implementation(libs.commons.lang3)
}

References

Version Catalogs

Tags

#version-catalog

Name Version Catalog Entries Appropriately

Consistent and descriptive names in your version catalog enhance readability and maintainability across your build scripts.

Explanation

Version catalogs provide a centralized way to manage dependencies by mapping full dependency coordinates to concise, reusable aliases like airlift-aircompressor. Adopting clear naming conventions for those aliases ensures that developers can easily identify and use dependencies throughout the project.

Aliases are typically made up of 1 to 3 segments. For example org.apache.commons:commons-lang3 could be represented as commonsLang3, apache-commonsLang3, or commons-lang3.

The following guidelines help in naming catalog entries effectively:

Use dashes to separate segments: Prefer hyphen/dashes (-) over underscores (_) to separate different parts of the entry name.

Example: For org.apache.logging.log4j:log4j-api, use log4j-api
Derive the first segment from the project group: Use a unique identifier from the project’s group ID as the first segment. Do not include the top level domain in the segment (com, org, net, dev).

Example: For com.fasterxml.jackson.core:jackson-databind, use jackson-databind or jackson-core-databind
Derive the second segment from the artifact ID: Use a unique identifier from the artifact ID as the second segment.

Example: For com.linecorp.armeria:armeria-grpc, use armeria-grpc
Avoid generic terms in the segments: Exclude terms that are obvious or implied in the context of your project (core, java, gradle, module, sdk), especially if the term appears by itself.

Example: For com.google.googlejavaformat:google-java-format, use google-java-format, not google-java or java
Omit redundant segments: If the group and artifact IDs are the same, avoid repeating them.

Example: For io.ktor:ktor-client-core, use ktor-client-core, not ktor-ktor-client-core
Convert internal dashes to camelCase: If the artifact ID contains dashes, convert them to camelCase for better readability in code.

Example: spring-boot-starter-web becomes springBootStarterWeb
Suffix plugin libraries with -plugin: When referencing a plugin as a library (not in the [plugins] section), append -plugin to the name.

Example: For org.owasp:dependency-check-gradle, use dependency-check-plugin

Example

gradle/libs.versions.toml

[versions]
slf4j = "2.0.13"
jackson = "2.17.1"
groovy = "3.0.5"
checkstyle = "8.37"
commonsLang = "3.9"

[libraries]
# SLF4J
slf4j-api = { module = "org.slf4j:slf4j-api", version.ref = "slf4j" }

# Jackson
jackson-databind = { module = "com.fasterxml.jackson.core:jackson-databind", version.ref = "jackson" }
jackson-dataformatCsv = { module = "com.fasterxml.jackson.dataformat:jackson-dataformat-csv", version.ref = "jackson" }

# Groovy bundle
groovy-core = { module = "org.codehaus.groovy:groovy", version.ref = "groovy" }
groovy-json = { module = "org.codehaus.groovy:groovy-json", version.ref = "groovy" }
groovy-nio = { module = "org.codehaus.groovy:groovy-nio", version.ref = "groovy" }

# Apache Commons Lang
commons-lang3 = { group = "org.apache.commons", name = "commons-lang3", version = { strictly = "[3.8, 4.0[", prefer = "3.9" } }

[bundles]
groovy = ["groovy-core", "groovy-json", "groovy-nio"]

[plugins]
versions = { id = "com.github.ben-manes.versions", version = "0.45.0" }

build.gradle.kts

plugins {
    id("java-library")
    alias(libs.plugins.versions)
}

repositories {
    mavenCentral()
}

dependencies {
    // SLF4J
    implementation(libs.slf4j.api)

    // Jackson
    implementation(libs.jackson.databind)
    implementation(libs.jackson.dataformatCsv)

    // Groovy bundle
    api(libs.bundles.groovy)

    // Commons Lang
    implementation(libs.commons.lang3)
}

build.gradle

plugins {
    id 'java-library'
    alias(libs.plugins.versions)
}

repositories {
    mavenCentral()
}

dependencies {
    // SLF4J
    implementation libs.slf4j.api

    // Jackson
    implementation libs.jackson.databind
    implementation libs.jackson.dataformatCsv

    // Groovy bundle
    api libs.bundles.groovy

    // Commons Lang
    implementation libs.commons.lang3
}

References

Best Practices for Naming Gradle Version Catalog Entries

Tags

#version-catalog

Set up your Dependency Repositories in the Settings file

Declare your repositories for your plugins and dependencies in settings.gradle.kts.

Explanation

Using settings.gradle.kts file to declare repositories has several benefits:

Avoids repetition: Centralizing repository declarations eliminates the need to repeat them in each project’s build.gradle.kts.
Improves debuggability: Ensures all projects resolve dependencies during resolution from the same repositories, in a consistent order.
Matches the build model: Repositories are not part of the project definition; they are part of global build logic, so settings is a more appropriate place for them.

Note	While `dependencyResolutionManagement.repositories` is an incubating API, it is the preferred way of declaring repositories.

Example

Don’t Do This

You could set up repositories in individual build.gradle.kts files with:

build.gradle.kts

buildscript {
    repositories {
        mavenCentral()
        gradlePluginPortal()
    }
}

plugins {
    id("java")
}

repositories {
    mavenCentral()
}

build.gradle

buildscript {
    repositories {
        mavenCentral()
        gradlePluginPortal()
    }
}

plugins {
    id("java")
}

repositories {
    mavenCentral()
}

Do This Instead

Instead, you should set them up in settings.gradle.kts like this:

settings.gradle.kts

pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement {
    repositoriesMode = RepositoriesMode.FAIL_ON_PROJECT_REPOS
    repositories {
        mavenCentral()
    }
}

settings.gradle

pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement {
    repositoriesMode = RepositoriesMode.FAIL_ON_PROJECT_REPOS
    repositories {
        mavenCentral()
    }
}

Tags

#structuring-builds, #repositories

Don’t Explicitly Depend on the Kotlin Standard Library

The Kotlin Gradle Plugin automatically adds a dependency on the Kotlin standard library (stdlib) to each source set, so there is no need to declare it explicitly.

Explanation

The version of the standard library added is the same as the version of the Kotlin Gradle Plugin applied to the project. If your build does not require a specific or different version of the standard library, you should avoid adding it manually.

Note

Setting the kotlin.stdlib.default.dependency property to false prevents the Kotlin plugin from automatically adding the Kotlin standard library dependency to your project. This can be useful in specific scenarios, such as when you want to manage the Kotlin standard library dependency version manually.

Example

Don’t Do This

build.gradle.kts

plugins {
    kotlin("jvm").version("2.4.0")
}

dependencies {
    api(kotlin("stdlib")) // (1)
}

build.gradle

plugins {
    id("org.jetbrains.kotlin.jvm") version "2.4.0"
}

dependencies {
    api("org.jetbrains.kotlin:kotlin-stdlib:2.4.0") // (1)
}

stdlib is explicitly depended upon: This project contains an implicit dependency on the Kotlin standard library, which is required to compile its source code.

Do This Instead

build.gradle.kts

plugins {
    kotlin("jvm").version("2.4.0") // (1)
}

build.gradle

plugins {
    id("org.jetbrains.kotlin.jvm") version "2.4.0"  // (1)
}

stdlib dependency is not included explicitly: The standard library remains available for use, and source code requiring it can be compiled without any issues.

References

the kotlin() function

Tags

Avoid Redundant Dependency Declarations

Avoid declaring the same dependency multiple times, especially when it is already available transitively or through another configuration.

Explanation

Duplicating dependencies in Gradle build scripts can lead to:

Increased maintenance: Declaring a dependency in multiple places makes it harder to manage.
Unexpected behavior: Declaring the same dependency in multiple configurations (e.g., compileOnly and implementation) can result in hard-to-diagnose classpath issues.

Example

Don’t Do This

build.gradle.kts

plugins {
    `java-library`
}

dependencies {
    api("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.0")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.0") // (1)
}

build.gradle

plugins {
    id 'java-library'
}

dependencies {
    api("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.0")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.0") // (1)
}

Redundant dependency in implementation scope.

Do This Instead

build.gradle.kts

plugins {
    `java-library`
}

dependencies {
    api("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.0") // (1)
}

build.gradle

plugins {
    id 'java-library'
}

dependencies {
    api("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.0") // (1)
}

Declare dependency once

Tags

Declare Dependencies using a single GAV (`group:artifact:version`) String

When declaring dependencies without a version catalog, prefer using the single GAV string notation implementation("org.example:library:1.0"). Avoid using the named argument notation. The named argument notation has been deprecated and will no longer be supported starting in Gradle 10.

Explanation

All of these declarations will be treated equivalently when Gradle resolves dependencies. However, the single-string form is more concise, easier to read, and is widely adopted in the broader JVM ecosystem.

This format is also recommended by Maven Central in its documentation and usage examples, making it the most familiar and consistent style for developers across tools.

Example

Don’t Do This

build.gradle.kts

dependencies {
    implementation(group = "com.fasterxml.jackson.core", name = "jackson-databind", version = "32.17.0")  // (1)
    api(group = "com.google.guava", name = "guava", version = "32.1.2-jre") {
        exclude(group = "com.google.code.findbugs", module = "jsr305")  // (2)
    }
}

build.gradle

dependencies {
    implementation(group: 'com.fasterxml.jackson.core', name: 'jackson-databind', version: '2.17.0') // (1)
    api(group: 'com.google.guava', name: 'guava', version: '32.1.2-jre') {
        exclude(group: 'com.google.code.findbugs', module: 'jsr305')    // (2)
    }
}

Avoid the named argument notation when declaring dependencies
Other modifiers methods and constraints like exclude are not included in this recommendation and can use named argument notation as needed

Do This Instead

build.gradle.kts

dependencies {
    implementation("com.fasterxml.jackson.core:jackson-databind:2.17.0") // (1)
    api("com.google.guava:guava:32.1.2-jre") {
        exclude(group = "com.google.code.findbugs", module = "jsr305")  // (2)
    }
}

build.gradle

dependencies {
    implementation('com.fasterxml.jackson.core:jackson-databind:2.17.0') // (1)
    api('com.google.guava:guava:32.1.2-jre') {
        exclude(group: 'com.google.code.findbugs', module: 'jsr305')    // (2)
    }
}

Use the string notation instead when declaring dependencies
Other modifiers methods and constraints like exclude are not included in this recommendation and can use named argument notation as needed

References

Declaring Dependencies Basics

Tags

Use Content Filtering with multiple Repositories

When using multiple repositories in a build, use repository content filtering to ensure that dependencies are resolved from an appropriate repository.

Explanation

If your build declares more than one repository, you should declare content filters on these repositories to ensure you search for and obtain dependencies from the correct place.

Content filtering is necessary if you have a reason to restrict searching for a dependency to a particular repository, and can be a good idea even if acceptable dependency artifacts exist in multiple locations.

When possible, you should use the exclusiveContent feature to restrict dependencies to a particular known repository.

Content filtering has three main benefits:

Performance, since you only query repositories for dependencies that should actually exist within them
Security, by avoiding asking potentially every repository for every dependency (even ones they shouldn’t contain), you improve resiliency to supply chain attacks by avoiding leaking information about your dependencies to other repositories, or even downloading potentially malicious artifacts
Reliability, by avoiding searching repositories that contain invalid or incorrect metadata for particular dependencies, which could result in obtaining incorrect transitive dependencies

Repositories will be searched for dependencies that pass their filters in the order they are declared. Often the last repository is declared without any filters in order to serve as a default fallback repository that is queried for any dependencies that don’t pass the filters present on the other repositories.

Warning

Carefully consider using content filtering with a fallback repository. This can pose a security risk, so make sure you fully trust the fallback repository. This setup can result in inadvertently (and silently) resolving dependencies from the fallback repository that were intended to come from filtered repositories if the dependencies were not available in those repositories.

Example

Don’t Do This

Don’t add multiple repositories without content filtering:

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        mavenCentral()
        google()
    }
}

settings.gradle

dependencyResolutionManagement {
    repositories {
        mavenCentral()
        google()
    }
}

Do This Instead

Use content filtering to ensure that the proper repositories are searched first for the expected artifacts:

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        google {
            content {
                // Use this repository for androidx and GMS dependencies
                includeGroupByRegex("androidx.*")
                includeGroup("com.google.gms")
            }
        }
        // Specify the fallback repository last
        mavenCentral()
    }
}

settings.gradle

dependencyResolutionManagement {
    repositories {
        google {
            content {
                // Use this repository for androidx and GMS dependencies
                includeGroupByRegex("androidx.*")
                includeGroup("com.google.gms")
            }
        }
        // Specify the fallback repository last
        mavenCentral()
    }
}

In many cases, it is better to use exclusive content filtering, as it ensures that dependencies can only be found in the expected repository. If they are not present there, they will not be found at all.

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        exclusiveContent {
            forRepository {
                google()
            }
            filter {
                // Only use this repository, and use this repository only, for androidx and GMS dependencies
                includeGroupByRegex("androidx.*")
                includeGroup("com.google.gms")
            }
        }
        // Specify the fallback repository last
        mavenCentral()
    }
}

settings.gradle

dependencyResolutionManagement {
    repositories {
        exclusiveContent {
            forRepository {
                google()
            }
            filter {
                // Only use this repository, and use this repository only, for androidx and GMS dependencies
                includeGroupByRegex("androidx.*")
                includeGroup("com.google.gms")
            }
        }
        // Specify the fallback repository last
        mavenCentral()
    }
}

References

Filtering Repository Content

Tags

#repositories, #dependencies

Apply Exclusions Narrowly

When excluding transitive dependencies, apply exclusions as narrowly as possible.

Explanation

Sometimes you may need to exclude transitive dependencies that cause conflicts or issues in your project.

Exclusions can negatively affect dependency resolution performance. Applying exclusions as narrowly as possible minimizes this impact. It also reduces the risks of inadvertently and silently excluding dependencies that are required elsewhere in your build, and of accidental runtime dependency clashes.

Gradle offers several ways to exclude transitive dependencies. When excluding transitive dependencies, keep the scope as narrow as possible:

Attach exclusions to specific dependencies rather than applying them to an entire configuration.
Exclude a single module from a group, instead of excluding the entire group.
Avoid global exclusions using configurations.all { … } or configurations.configureEach { … }.

Example

Don’t Do This

build.gradle.kts

dependencies {
    implementation("org.apache.commons:commons-pool2:2.12.1") // (1)
    implementation("org.hibernate:hibernate-core:3.6.10.Final")
    // ... other dependencies ...
}

configurations {
    "implementation" {
        exclude(group = "cglib") // (2)
    }

    "implementation" {
        exclude(group = "org.ow2.asm", module = "asm-util") // (3)
    }
}

configurations.configureEach {
    exclude(group = "javassist", module = "javassist") // (4)
}

build.gradle

dependencies {
    implementation("org.apache.commons:commons-pool2:2.12.1") // (1)
    implementation("org.hibernate:hibernate-core:3.6.10.Final")
    // ... other dependencies ...
}

configurations {
    implementation {
        exclude(group: "cglib") // (2)
    }

    implementation {
        exclude(group: "org.ow2.asm", module: "asm-util") // (3)
    }
}

configurations.configureEach {
    exclude(group: "javassist", module: "javassist") // (4)
}

The commons-pool2 dependency transitively includes cglib:cglib and org.ow2.asm:asm-util as optional dependencies - we want to exclude both. hibernate-core transitively optionally includes cglib:cglib, and also javaassist:javassist - we want to exclude both.
This excludes every module provided by the cglib group from every dependency in the implementation configuration. If other current or future dependencies in this project rely on different modules from cglib, those dependencies may fail to resolve, leading to compilation or runtime errors.
This excludes org.ow2.asm:asm-util from every dependency in the implementation configuration. If future dependencies rely on org.ow2.asm:asm-util, they may fail at compile or runtime because the module will be silently excluded.
This excludes javaassist:javassist from all dependencies in all configurations, including those added by plugins or in the future, which carries the same risks as above, but on a larger scale.

Do This Instead

Exclude transitive dependencies as narrowly as possible, ideally on individual dependencies:

build.gradle.kts

dependencies {
    implementation("org.apache.commons:commons-pool2:2.12.1") { // (1)
        exclude(group = "cglib", module = "cglib") // (2)
        exclude(group = "org.ow2.asm", module = "asm-util")

    }
    implementation("org.hibernate:hibernate-core:3.6.10.Final") {
        exclude(group = "cglib", module = "cglib")
        exclude(group = "javassist", module = "javassist") // (3)
    }
    // ... other dependencies ...
}

build.gradle

dependencies {
    implementation("org.apache.commons:commons-pool2:2.12.1") { // (1)
        exclude(group: "cglib", module: "cglib") // (2)
        exclude(group: "org.ow2.asm", module: "asm-util")

    }
    implementation("org.hibernate:hibernate-core:3.6.10.Final") {
        exclude(group: "cglib", module: "cglib")
        exclude(group: "javassist", module: "javassist") // (3)
    }
    // ... other dependencies ...
}

Exclusions are applied only to the dependency that actually transitively includes them.
All exclusions apply to a particular module instead of every module from a particular group.
javaassist:javassist is only excluded from the hibernate-core dependency - the only dependency that transitively includes it.

Though it may seem repetitive to exclude the same transitive dependencies from multiple dependencies, this approach is safer, more performant, less likely to cause accidental runtime crashes, and makes it clearer which dependencies are affected by each exclusion.

References

Excluding Transitive Dependencies

Tags

Always Declare Attributes on Consumable and Resolvable Configurations

When creating custom configurations that are meant to be consumed or resolved, always declare at least one attribute on them.

Explanation

Gradle uses variant-aware dependency resolution to select the appropriate variants of a project. Attributes serve as the primary matching mechanism between resolvable configurations (what a consumer needs) and consumable configurations (what a producer provides as variants).

Even if a producer project has only one consumable configuration, omitting attributes will cause variant-aware resolution to fail with the following error:

Unable to find a matching variant of project :producer:
  - No variants exist.

While Gradle can resolve configurations by selecting them directly by name, this approach is outdated:

It was deprecated for Maven repositories in Gradle 8.10 and removed in Gradle 9.0.0. It is only necessary for use with Ivy repositories. This mechanism can still be used for local project dependencies, but should be avoided.
Configuration names should be treated as internal implementation details. Relying on them for resolution forces the consumer to know too much about the producer’s internal structure.

When adding attributes to a configuration, common attributes to use include:

Category.CATEGORY_ATTRIBUTE - Indicates the category of the component (e.g., LIBRARY, DOCUMENTATION)
For JVM Projects:
- Usage.USAGE_ATTRIBUTE - Indicates which classpath this variant represents (e.g., JAVA_RUNTIME, JAVA_API)
- LibraryElements.LIBRARY_ELEMENTS_ATTRIBUTE - Indicates the packaging of the classes (e.g., JAR, CLASSES)

While attributes are not yet strictly required for all resolvable configurations, omitting them leads to fragile builds. Declaring sensible attributes ensures your build remains reliable as it scales and evolves.

Example

Don’t Do This

Avoid creating consumable and resolvable configurations without attributes:

In producer/build.gradle(.kts):

producer/build.gradle.kts

configurations.consumable("customElements") // (1)

val generateFile = tasks.register("generateFile") {
    val outputFile = layout.buildDirectory.file("custom/output.txt")
    outputs.file(outputFile)
    doLast {
        outputFile.get().asFile.writeText("Custom output from producer")
    }
}

artifacts {
    add("customElements", generateFile)
}

producer/build.gradle

configurations.consumable('customElements') // (1)

def generateFile = tasks.register('generateFile') {
    def outputFile = layout.buildDirectory.file('custom/output.txt')
    outputs.file(outputFile)
    doLast {
        outputFile.get().asFile.text = 'Custom output from producer'
    }
}

artifacts {
    customElements generateFile
}

No attributes declared on the configuration in the producer build: This consumable configuration lacks attributes to describe what it provides.

In consumer/build.gradle(.kts):

consumer/build.gradle.kts

val customElementsDependencies = configurations.dependencyScope("customElementsDependencies")

dependencies {
    customElementsDependencies(project(path = ":producer", configuration = "customElements"))
}

val customElements = configurations.resolvable("customElements") { // (1)
    extendsFrom(customElementsDependencies.get())
}

tasks.register("resolveCustom") {
    inputs.files(customElements.get())
    doLast {
        inputs.files.forEach { file: File ->
            logger.lifecycle("Resolved: ${file.name}")
        }
    }
}

consumer/build.gradle

def customElementsDependenciesProvider = configurations.dependencyScope('customElementsDependencies')

dependencies {
    customElementsDependencies(project(path: ':producer', configuration: 'customElements'))
}

def customElements = configurations.resolvable('customElements') { // (1)
    extendsFrom(customElementsDependenciesProvider.get())
}

tasks.register('resolveCustom') {
    inputs.files(customElements)
    doLast {
        inputs.files.each { file ->
            logger.lifecycle("Resolved: ${file.name}")
        }
    }
}

No attributes declared on the configuration in the consumer build: This resolvable configuration lacks attributes to describe what it needs.

This approach works only because we explicitly name the configuration in the dependency declaration (configuration = "customElements"). Resolving configurations by name should be avoided.

Do This Instead

Always declare attributes on consumable and resolvable configurations:

In producer/build.gradle(.kts):

producer/build.gradle.kts

val CUSTOM_ATTRIBUTE = Attribute.of("custom", String::class.java) // (1)
dependencies.attributesSchema.attribute(CUSTOM_ATTRIBUTE)

val generateFile = tasks.register("generateFile") {
    val outputFile = layout.buildDirectory.file("custom/output.txt")
    outputs.file(outputFile)
    doLast {
        outputFile.get().asFile.writeText("Custom output from producer")
    }
}

configurations {
    consumable("customElements") {
        attributes { // (2)
            attribute(Category.CATEGORY_ATTRIBUTE, objects.named(Category.LIBRARY))
            attribute(CUSTOM_ATTRIBUTE, "my-custom-value")
        }
        outgoing {
            artifact(generateFile)
        }
    }
}

producer/build.gradle

def CUSTOM_ATTRIBUTE = Attribute.of("custom", String) // (1)
dependencies.attributesSchema.attribute(CUSTOM_ATTRIBUTE)

def generateFile = tasks.register('generateFile') {
    def outputFile = layout.buildDirectory.file('custom/output.txt')
    outputs.file(outputFile)
    doLast {
        outputFile.get().asFile.text = 'Custom output from producer'
    }
}

configurations {
    consumable('customElements') {
        attributes { // (2)
            attribute(Category.CATEGORY_ATTRIBUTE, objects.named(Category, Category.LIBRARY))
            attribute(CUSTOM_ATTRIBUTE, "my-custom-value")
        }
        outgoing {
            artifact(generateFile)
        }
    }
}

New Attribute type defined in producer: The consumable configuration defines a new custom attribute that contains project-specific variant identification information. The new Attribute is also added to the Gradle Attribute schema to ensure type-safety.
Attributes declared in producer: The consumable configuration adds Category = LIBRARY, and custom attribute = my-custom-value. These attributes will be used to identify this variant during resolution.

In consumer/build.gradle(.kts):

consumer/build.gradle.kts

val customElementsDependencies = configurations.dependencyScope("customElementsDependencies")

dependencies {
    customElementsDependencies(project(":producer")) // (1)
}

val CUSTOM_ATTRIBUTE = Attribute.of("custom", String::class.java) // (2)
dependencies.attributesSchema.attribute(CUSTOM_ATTRIBUTE)

val customElements = configurations.resolvable("customElements") {
    extendsFrom(customElementsDependencies.get())
    attributes { // (3)
        attribute(Category.CATEGORY_ATTRIBUTE, objects.named(Category.LIBRARY))
        attribute(CUSTOM_ATTRIBUTE, "my-custom-value")
    }
}

tasks.register("resolveCustom") {
    inputs.files(customElements.get())
    doLast {
        inputs.files.forEach { file: File ->
            logger.lifecycle("Resolved: ${file.name}")
        }
    }
}

consumer/build.gradle

def customElementsDependenciesProvider = configurations.dependencyScope('customElementsDependencies')

dependencies {
    customElementsDependencies(project(':producer')) // (1)
}

def CUSTOM_ATTRIBUTE = Attribute.of("custom", String) // (2)
dependencies.attributesSchema.attribute(CUSTOM_ATTRIBUTE)


def customElements = configurations.resolvable('customElements') {
    extendsFrom(customElementsDependenciesProvider.get())
    attributes { // (3)
        attribute(Category.CATEGORY_ATTRIBUTE, objects.named(Category, Category.LIBRARY))
        attribute(CUSTOM_ATTRIBUTE, "my-custom-value")
    }
}


tasks.register('resolveCustom') {
    inputs.files(customElements)
    doLast {
        inputs.files.each { file ->
            logger.lifecycle("Resolved: ${file.name}")
        }
    }
}

The project dependency does not use configuration name: It is no longer necessary to specify the configuration name in the dependency declaration, as variant-aware dependency resolution will be used to select the correct variant.
New Attribute type defined in consumer: The resolvable configuration defines the same new custom attribute that contains project-specific variant identification information.
Attributes declared in consumer: The resolvable configuration is identified as Category = LIBRARY, and custom attribute = my-custom-value.

By declaring compatible attributes, you decouple your projects from internal naming conventions, resulting in a more robust and maintainable build.

References

Tags

Best Practices for Tasks

Avoid DependsOn

The task dependsOn method should only be used for lifecycle tasks (tasks without task actions).

Explanation

Tasks with actions should declare their inputs and outputs so that Gradle’s up-to-date checking can automatically determine when these tasks need to be run or rerun.

Using dependsOn to link tasks is a much coarser-grained mechanism that does not allow Gradle to understand why a task requires a prerequisite task to run, or which specific files from a prerequisite task are needed. dependsOn forces Gradle to assume that every file produced by a prerequisite task is needed by this task. This can lead to unnecessary task execution and decreased build performance.

Example

Here is a task that writes output to two separate files:

build.gradle.kts

abstract class SimplePrintingTask : DefaultTask() {
    @get:OutputFile
    abstract val messageFile: RegularFileProperty

    @get:OutputFile
    abstract val audienceFile: RegularFileProperty

    @TaskAction // (1)
    fun run() {
        messageFile.get().asFile.writeText("Hello")
        audienceFile.get().asFile.writeText("World")
    }
}

tasks.register<SimplePrintingTask>("helloWorld") { // (2)
    messageFile.set(layout.buildDirectory.file("message.txt"))
    audienceFile.set(layout.buildDirectory.file("audience.txt"))
}

build.gradle

abstract class SimplePrintingTask extends DefaultTask {
    @OutputFile
    abstract RegularFileProperty getMessageFile()

    @OutputFile
    abstract RegularFileProperty getAudienceFile()

    @TaskAction // (1)
    void run() {
        messageFile.get().asFile.write("Hello")
        audienceFile.get().asFile.write("World")
    }
}

tasks.register("helloWorld", SimplePrintingTask) { // (2)
    messageFile = layout.buildDirectory.file("message.txt")
    audienceFile = layout.buildDirectory.file("audience.txt")
}

Task With Multiple Outputs: helloWorld task prints "Hello" to its messageFile and "World" to its audienceFile.
Registering the Task: helloWorld produces "message.txt" and "audience.txt" outputs.

Don’t Do This

If you want to translate the greeting in the message.txt file using another task, you could do this:

build.gradle.kts

abstract class SimpleTranslationTask : DefaultTask() {
    @get:InputFile
    abstract val messageFile: RegularFileProperty

    @get:OutputFile
    abstract val translatedFile: RegularFileProperty

    init {
        messageFile.convention(project.layout.buildDirectory.file("message.txt"))
        translatedFile.convention(project.layout.buildDirectory.file("translated.txt"))
    }

    @TaskAction // (1)
    fun run() {
        val message = messageFile.get().asFile.readText(Charsets.UTF_8)
        val translatedMessage = if (message == "Hello") "Bonjour" else "Unknown"

        logger.lifecycle("Translation: " + translatedMessage)
        translatedFile.get().asFile.writeText(translatedMessage)
    }
}

tasks.register<SimpleTranslationTask>("translateBad") {
    dependsOn(tasks.named("helloWorld")) // (2)
}

build.gradle

abstract class SimpleTranslationTask extends DefaultTask {
    @InputFile
    abstract RegularFileProperty getMessageFile()

    @OutputFile
    abstract RegularFileProperty getTranslatedFile()

    SimpleTranslationTask() {
        messageFile.convention(project.layout.buildDirectory.file("message.txt"))
        translatedFile.convention(project.layout.buildDirectory.file("translated.txt"))
    }

    @TaskAction // (1)
    void run() {
        def message = messageFile.get().asFile.text
        def translatedMessage = message == "Hello" ? "Bonjour" : "Unknown"

        logger.lifecycle("Translation: " + translatedMessage)
        translatedFile.get().asFile.write(translatedMessage)
    }
}

tasks.register("translateBad", SimpleTranslationTask) {
    dependsOn(tasks.named("helloWorld")) // (2)
}

Translation Task Setup: translateBad requires helloWorld to run first to produce the message file otherwise it will fail with an error as the file does not exist.
Explicit Task Dependency: Running translateBad will cause helloWorld to run first, but Gradle does not understand why.

Do This Instead

Instead, you should explicitly wire task inputs and outputs like this:

build.gradle.kts

abstract class SimpleTranslationTask : DefaultTask() {
    @get:InputFile
    abstract val messageFile: RegularFileProperty

    @get:OutputFile
    abstract val translatedFile: RegularFileProperty

    init {
        messageFile.convention(project.layout.buildDirectory.file("message.txt"))
        translatedFile.convention(project.layout.buildDirectory.file("translated.txt"))
    }

    @TaskAction // (1)
    fun run() {
        val message = messageFile.get().asFile.readText(Charsets.UTF_8)
        val translatedMessage = if (message == "Hello") "Bonjour" else "Unknown"

        logger.lifecycle("Translation: " + translatedMessage)
        translatedFile.get().asFile.writeText(translatedMessage)
    }
}

tasks.register<SimpleTranslationTask>("translateGood") {
    inputs.file(tasks.named<SimplePrintingTask>("helloWorld").map { messageFile }) // (1)
}

build.gradle

abstract class SimpleTranslationTask extends DefaultTask {
    @InputFile
    abstract RegularFileProperty getMessageFile()

    @OutputFile
    abstract RegularFileProperty getTranslatedFile()

    SimpleTranslationTask() {
        messageFile.convention(project.layout.buildDirectory.file("message.txt"))
        translatedFile.convention(project.layout.buildDirectory.file("translated.txt"))
    }

    @TaskAction // (1)
    void run() {
        def message = messageFile.get().asFile.text
        def translatedMessage = message == "Hello" ? "Bonjour" : "Unknown"

        logger.lifecycle("Translation: " + translatedMessage)
        translatedFile.get().asFile.write(translatedMessage)
    }
}

tasks.register("translateGood", SimpleTranslationTask) {
    inputs.file(tasks.named("helloWorld", SimplePrintingTask).map { messageFile }) // (1)
}

Register Implicit Task Dependency: translateGood requires only one of the files that is produced by helloWorld.

Gradle now understands that translateGood requires helloWorld to have run successfully first because it needs to create the message.txt file which is then used by the translation task. Gradle can use this information to optimize task scheduling. Using the map method avoids eagerly retrieving the helloWorld task until the output is needed to determine if translateGood should run.

References

Task Inputs and Outputs

Tags

#tasks, #inputs-and-outputs, #up-to-date-checking

Favor `@CacheableTask` and `@DisableCachingByDefault` over `cacheIf(Spec)` and `doNotCacheIf(String, Spec)`

The cacheIf and doNotCacheIf methods should only be used in situations where the cacheability of a task varies between different task instances or cannot be determined until the task is executed by Gradle. You should instead favor annotating the task class itself with @CacheableTask annotation for any task that is always cacheable. Likewise, the @DisableCachingByDefault should be used to always disable caching for all instances of a task type.

Explanation

Annotating a task type will ensure that each task instance of that type is properly understood by Gradle to be cacheable (or not cacheable). This removes the need to remember to configure each of the task instances separately in build scripts.

Using the annotations also documents the intended cacheability of the task type within its own source, appearing in Javadoc and making the task’s behavior clear to other developers without requiring them to inspect each task instance’s configuration. It is also slightly more efficient than running a test to determine cacheability.

Remember that only tasks that produce reproducible and relocatable output should be marked as @CacheableTask.

Example

Don’t Do This

If you want to reuse the output of a task, you shouldn’t do this:

build.gradle.kts

abstract class BadCalculatorTask : DefaultTask() { // (1)
    @get:Input
    abstract val first: Property<Int>

    @get:Input
    abstract val second: Property<Int>

    @get:OutputFile
    abstract val outputFile: RegularFileProperty

    @TaskAction
    fun run() {
        val result = first.get() + second.get()
        logger.lifecycle("Result: $result")
        outputFile.get().asFile.writeText(result.toString())
    }
}

tasks.register<Delete>("clean") {
    delete(layout.buildDirectory)
}

tasks.register<BadCalculatorTask>("addBad1") {
    first = 10
    second = 25
    outputFile = layout.buildDirectory.file("badOutput.txt")
    outputs.cacheIf { true } // (2)
}

tasks.register<BadCalculatorTask>("addBad2") { // (3)
    first = 3
    second = 7
    outputFile = layout.buildDirectory.file("badOutput2.txt")
}

build.gradle

abstract class BadCalculatorTask extends DefaultTask {
    @Input
    abstract Property<Integer> getFirst()

    @Input
    abstract Property<Integer> getSecond()

    @OutputFile
    abstract RegularFileProperty getOutputFile()

    @TaskAction
    void run() {
        def result = first.get() + second.get()
        logger.lifecycle("Result: " + result)
        outputFile.get().asFile.write(result.toString())
    }
}

tasks.register("clean", Delete) {
    delete layout.buildDirectory
}

tasks.register("addBad1", BadCalculatorTask) {
    first = 10
    second = 25
    outputFile = layout.buildDirectory.file("badOutput.txt")
    outputs.cacheIf { true }
}

tasks.register("addBad2", BadCalculatorTask) {
    first = 3
    second = 7
    outputFile = layout.buildDirectory.file("badOutput2.txt")
}

Define a Task: The BadCalculatorTask type is deterministic and produces relocatable output, but is not annotated.
Mark the Task Instance as Cacheable: This example shows how to mark a specific task instance as cacheable.
Forget to Mark a Task Instance as Cacheable: Unfortunately, the addBad2 instance of the BadCalculatorTask type is not marked as cacheable, so it will not be cached, despite behaving the same as addBad1.

Do This Instead

As this task meets the criteria for cacheability (we can imagine a more complex calculation in the @TaskAction that would benefit from automatic work avoidance via caching), you should mark the task type itself as cacheable like this:

build.gradle.kts

@CacheableTask // (1)
abstract class GoodCalculatorTask : DefaultTask() {
    @get:Input
    abstract val first: Property<Int>

    @get:Input
    abstract val second: Property<Int>

    @get:OutputFile
    abstract val outputFile: RegularFileProperty

    @TaskAction
    fun run() {
        val result = first.get() + second.get()
        logger.lifecycle("Result: $result")
        outputFile.get().asFile.writeText(result.toString())
    }
}

tasks.register<Delete>("clean") {
    delete(layout.buildDirectory)
}

tasks.register<GoodCalculatorTask>("addGood1") { // (2)
    first = 10
    second = 25
    outputFile = layout.buildDirectory.file("goodOutput.txt")
}

tasks.register<GoodCalculatorTask>("addGood2") {
    first = 3
    second = 7
    outputFile = layout.buildDirectory.file("goodOutput2.txt")
}

build.gradle

@CacheableTask // (1)
abstract class GoodCalculatorTask extends DefaultTask {
    @Input
    abstract Property<Integer> getFirst()

    @Input
    abstract Property<Integer> getSecond()

    @OutputFile
    abstract RegularFileProperty getOutputFile()

    @TaskAction
    void run() {
        def result = first.get() + second.get()
        logger.lifecycle("Result: " + result)
        outputFile.get().asFile.write(result.toString())
    }
}

tasks.register("clean", Delete) {
    delete layout.buildDirectory
}

tasks.register("addGood1", GoodCalculatorTask) {
    first = 10
    second = 25
    outputFile = layout.buildDirectory.file("goodOutput.txt")
}

tasks.register("addGood2", GoodCalculatorTask) { // (2)
    first = 3
    second = 7
    outputFile = layout.buildDirectory.file("goodOutput2.txt")
}

Annotate the Task Type: Applying the @CacheableTask to a task type informs Gradle that instances of this task should always be cached.
Nothing Else Needs To Be Done: When we register task instances, nothing else needs to be done - Gradle knows to cache them.

References

Tags

#tasks, #caching

Do not call `get()` on a Provider outside a Task action

When configuring tasks and extensions do not call get() on a provider, use map(), or flatMap() instead.

Explanation

A provider should be evaluated as late as possible. Calling get() forces immediate evaluation, which can trigger unintended side effects, such as:

The value of the provider becomes an input to configuration, causing potential configuration cache misses.
The value may be evaluated too early, meaning you might not be using the final or correct value of the property. This may lead to painful and hard to debug ordering issues.
It breaks Gradle’s ability to build dependencies and to track task inputs and outputs, making automatic task dependency wiring impossible. See Working with task inputs and outputs

It is preferable to avoid explicitly evaluating a Provider at all, and deferring to map/flatMap to connect Providers to Providers implicitly.

Example

Here is a task that writes an input String to a file:

build.gradle.kts

abstract class MyTask : DefaultTask() {
    @get:Input
    abstract val myInput: Property<String>

    @get:OutputFile
    abstract val myOutput: RegularFileProperty

    @TaskAction
    fun doAction() {
        val outputFile = myOutput.get().asFile
        val outputText = myInput.get() // (1)
        println(outputText)
        outputFile.writeText(outputText)
    }
}

val currentEnvironment: Provider<String> = providers.gradleProperty("currentEnvironment").orElse("234") // (2)

build.gradle

abstract class MyTask extends DefaultTask {
    @Input
    abstract Property<String> getMyInput()

    @OutputFile
    abstract RegularFileProperty getMyOutput()

    @TaskAction
    void doAction() {
        def outputFile = myOutput.get().asFile
        def outputText = myInput.get() // (1)
        println(outputText)
        outputFile.write(outputText)
    }
}

Provider<String> currentEnvironment = providers.gradleProperty("currentEnvironment").orElse("234") // (2)

Using Provider.get() in the task action
Gradle property that we wish to use as input

Don’t Do This

You could call get() at configuration time to set up this task:

build.gradle.kts

tasks.register<MyTask>("avoidThis") {
    myInput = "currentEnvironment=${currentEnvironment.get()}"  // (1)
    myOutput = layout.buildDirectory.get().asFile.resolve("output-avoid.txt")  // (2)
}

build.gradle

tasks.register("avoidThis", MyTask) {
    myInput = "currentEnvironment=${currentEnvironment.get()}"  // (1)
    myOutput = new File(layout.buildDirectory.get().asFile, "output-avoid.txt")  // (2)
}

Reading the value of currentEnvironment at configuration time: This value might change by the time the task start executing.
Reading the value of buildDirectory at configuration time: This value might change by the time the task start executing.

Do This Instead

Instead, you should explicitly wire task inputs and outputs like this:

build.gradle.kts

tasks.register<MyTask>("doThis") {
    myInput = currentEnvironment.map { "currentEnvironment=$it" }  // (1)
    myOutput = layout.buildDirectory.file("output-do.txt")  // (2)
}

build.gradle

tasks.register("doThis", MyTask) {
    myInput = currentEnvironment.map { "currentEnvironment=$it" }  // (1)
    myOutput = layout.buildDirectory.file("output-do.txt")  // (2)
}

Using map() to transform currentEnvironment: map transform runs only when the value is read.
Using file() to create a new Provider<RegularFile>: the value of the buildDirectory is only checked when the value of the provider is read.

References

Task Inputs and Outputs

Tags

Group and Describe custom Tasks

When defining custom task types or registering ad-hoc tasks, always set a clear group and description.

Explanation

A good group name is short, lowercase, and reflects the purpose or domain of the task. For example: documentation, verification, release, or publishing.

Before creating a new group, look for an existing group name that aligns with your task’s intent. It’s often better to reuse an established category to keep the task output organized and familiar to users.

This information is used in the Tasks Report (shown via ./gradlew tasks) to group and describe available tasks in a readable format.

Providing a group and description ensures that your tasks are:

Displayed clearly in the report
Categorized appropriately
Understandable to other users (and to your future self)

Note	Tasks with no group are hidden from the Tasks Report unless `--all` is specified.

Example

Don’t Do This

Tasks without a group appear under the "other" category in ./gradlew tasks --all output, making them harder to locate:

app/build.gradle.kts

tasks.register("generateDocs") {
    // Build logic to generate documentation
}

app/build.gradle

tasks.register('generateDocs') {
    // Build logic to generate documentation
}

$ gradlew :app:tasks --all

> Task :app:tasks

------------------------------------------------------------
Tasks runnable from project ':app'
------------------------------------------------------------

Other tasks
-----------
compileJava - Compiles main Java source.
compileTestJava - Compiles test Java source.
generateDocs
processResources - Processes main resources.
processTestResources - Processes test resources.
startScripts - Creates OS specific scripts to run the project as a JVM application.

Do this Instead

When defining custom tasks, always assign a clear group and description:

app/build.gradle.kts

tasks.register("generateDocs") {
    group = "documentation"
    description = "Generates project documentation from source files."
    // Build logic to generate documentation
}

app/build.gradle

tasks.register('generateDocs') {
    group = 'documentation'
    description = 'Generates project documentation from source files.'
    // Build logic to generate documentation
}

$ gradlew :app:tasks --all

> Task :app:tasks

------------------------------------------------------------
Tasks runnable from project ':app'
------------------------------------------------------------

Documentation tasks
-------------------
generateDocs - Generates project documentation from source files.
javadoc - Generates Javadoc API documentation for the 'main' feature.

References

Task Group and Description

Tags

#tasks

Avoid using eager APIs on File Collections

When working with Gradle’s file collection types, be careful to avoid triggering dependency resolution during the configuration phase.

Explanation

Gradle’s Configuration and FileCollection types extend the JDK’s Collection<File> interface.

However, calling some available methods from this interface—such as .size(), .isEmpty(), getFiles(), asPath(), or .toList()—on these Gradle types will implicitly trigger resolution of their dependencies. The same is possible using Kotlin stdlib collection extension methods or Groovy GDK collection extensions. Converting a Configuration to a Set<File> also discards any implicit task dependencies it carries.

You should avoid using these methods when configuring your build. Instead, use the methods defined directly on the Gradle interfaces - this is a necessary first step towards preventing eager resolutions. Be sure to use lazy types and APIs that defer resolution to wire task dependencies and inputs correctly. Some methods that cause resolution are not obvious. Be sure to check the actual behavior when using configurations in an atypical way.

Example

Don’t Do This

build.gradle.kts

abstract class FileCounterTask: DefaultTask() {
    @get:InputFiles
    abstract val countMe: ConfigurableFileCollection

    @TaskAction
    fun countFiles() {
        logger.lifecycle("Count: " + countMe.files.size)
    }
}

tasks.register<FileCounterTask>("badCountingTask") {
    if (!configurations.runtimeClasspath.get().isEmpty()) { // (1)
        logger.lifecycle("Resolved: " + (configurations.runtimeClasspath.get().state == RESOLVED))
        countMe.from(configurations.runtimeClasspath)
    }
}

tasks.register<FileCounterTask>("badCountingTask2") {
    val files = configurations.runtimeClasspath.get().files // (2)
    countMe.from(files)
    logger.lifecycle("Resolved: " + (configurations.runtimeClasspath.get().state == RESOLVED))
}

tasks.register<FileCounterTask>("badCountingTask3") {
    val files = configurations.runtimeClasspath.get() + layout.projectDirectory.file("extra.txt") // (3)
    countMe.from(files)
    logger.lifecycle("Resolved: " + (configurations.runtimeClasspath.get().state == RESOLVED))
}

tasks.register<Zip>("badZippingTask") { // (4)
    if (!configurations.runtimeClasspath.get().isEmpty()) {
        logger.lifecycle("Resolved: " + (configurations.runtimeClasspath.get().state == RESOLVED))
        from(configurations.runtimeClasspath)
    }
}

build.gradle

abstract class FileCounterTask extends DefaultTask {
    @InputFiles
    abstract ConfigurableFileCollection getCountMe();

    @TaskAction
    void countFiles() {
        logger.lifecycle("Count: " + countMe.files.size())
    }
}

tasks.register("badCountingTask", FileCounterTask) {
    if (!configurations.runtimeClasspath.isEmpty()) { // (1)
        logger.lifecycle("Resolved: " + (configurations.runtimeClasspath.state == RESOLVED))
        countMe.from(configurations.runtimeClasspath)
    }
}

tasks.register("badCountingTask2", FileCounterTask) {
    def files = configurations.runtimeClasspath.files // (2)
    countMe.from(files)
    logger.lifecycle("Resolved: " + (configurations.runtimeClasspath.state == RESOLVED))
}

tasks.register("badCountingTask3", FileCounterTask) {
    def files = configurations.runtimeClasspath + layout.projectDirectory.file("extra.txt") // (3)
    countMe.from(files)
    logger.lifecycle("Resolved: " + (configurations.runtimeClasspath.state == RESOLVED))
}

tasks.register("badZippingTask", Zip) { // (4)
    if (!configurations.runtimeClasspath.isEmpty()) {
        logger.lifecycle("Resolved: " + (configurations.runtimeClasspath.state == RESOLVED))
        from(configurations.runtimeClasspath)
    }
}

isEmpty() causes resolution: Many seemingly harmless Collection API methods like isEmpty() cause Gradle to resolve dependencies.
Accessing files directly: Using getFiles() to access the files in a Configuration will also cause Gradle to resolve the file collection.
Adding a file via plus operator: Using the plus operator will force the runtimeClasspath configuration to be resolved implicitly. The implementation of Configuration doesn’t override the plus operator for regular files, therefore it falls back to using the eager API, which causes resolution.
Be careful with indirect inputs: Some built-in tasks, for example subtypes of AbstractCopyTask like Zip, allow adding inputs indirectly and can have the same problems.

Do This Instead

To avoid issues, always defer resolution until the execution phase. Use APIs that support lazy evaluation.

build.gradle.kts

abstract class FileCounterTask: DefaultTask() {
    @get:InputFiles
    abstract val countMe: ConfigurableFileCollection

    @TaskAction
    fun countFiles() {
        logger.lifecycle("Count: " + countMe.files.size)
    }
}

tasks.register<FileCounterTask>("goodCountingTask") {
    countMe.from(configurations.runtimeClasspath) // (1)
    countMe.from(layout.projectDirectory.file("extra.txt"))
    logger.lifecycle("Resolved: " + (configurations.runtimeClasspath.get().state == RESOLVED))
}

build.gradle

abstract class FileCounterTask extends DefaultTask {
    @InputFiles
    abstract ConfigurableFileCollection getCountMe();

    @TaskAction
    void countFiles() {
        logger.lifecycle("Count: " + countMe.files.size())
    }
}

tasks.register("goodCountingTask", FileCounterTask) {
    countMe.from(configurations.runtimeClasspath) // (1)
    countMe.from(layout.projectDirectory.file("extra.txt")) // (2)
    logger.lifecycle("Resolved: " + (configurations.runtimeClasspath.state == RESOLVED))
}

Add configurations to Task properties or Specs directly: This will defer resolution until the task is executed.
Add files to Specs separately: This allows combining files with file collections without triggering implicit resolutions.

Tags

#tasks, #inputs-and-outputs, #configurations

Don’t resolve Configurations before Task Execution

Resolving configurations before the task execution phase can lead to incorrect results and slower builds.

Explanation

Resolving a configuration - either directly via calling its resolve() method or indirectly via accessing its set of artifacts - returns a set of files that does not preserve references to the tasks that produced those files.

Configurations are file collections and can be added to @InputFiles properties on other tasks. It is important to do this correctly to avoid breaking automatic task dependency wiring between a consumer task and any tasks that are implicitly required to produce the artifacts being consumed. For example, if a configuration contains a project dependency, Gradle knows that consumers of the configuration must first run any tasks that produce that project’s artifacts.

In addition to correctness concerns, resolving configurations during the configuration phase can slow down the build, even when running unrelated tasks (e.g., help) that don’t require the resolved dependencies.

Example

Don’t Do This

build.gradle.kts

dependencies {
    runtimeOnly(project(":lib")) // (1)
}

abstract class BadClasspathPrinter : DefaultTask() {
    @get:InputFiles
    var classpath: Set<File> = emptySet() // (2)

    private fun calculateDigest(fileOrDirectory: File): Int {
        require(fileOrDirectory.exists()) { "File or directory $fileOrDirectory doesn't exist" }
        return 0 // actual implementation is stripped
    }

    @TaskAction
    fun run() {
        logger.lifecycle(
            classpath.joinToString("\n") {
                val digest = calculateDigest(it) // (3)
                "$it#$digest"
            }
        )
    }
}

tasks.register("badClasspathPrinter", BadClasspathPrinter::class) {
    classpath = configurations.named("runtimeClasspath").get().resolve() // (4)
}

build.gradle

dependencies {
    runtimeOnly(project(":lib")) // (1)
}

abstract class BadClasspathPrinter extends DefaultTask {
    @InputFiles
    Set<File> classpath = [] as Set // (2)

    protected int calculateDigest(File fileOrDirectory) {
        if (!fileOrDirectory.exists()) {
            throw new IllegalArgumentException("File or directory $fileOrDirectory doesn't exist")
        }
        return 0 // actual implementation is stripped
    }

    @TaskAction
    void run() {
        logger.lifecycle(
            classpath.collect { file ->
                def digest = calculateDigest(file) // (3)
                "$file#$digest"
            }.join("\n")
        )
    }
}

tasks.register("badClasspathPrinter", BadClasspathPrinter) {
    classpath = configurations.named("runtimeClasspath").get().resolve() // (4)
}

Add project dependency: The :lib project must be built in order to resolve the runtime classpath successfully.
Declare input property as Set of files: A simple Set input doesn’t track task dependencies.
Dependency artifacts are used to calculate digest: Artifacts from the already resolved classpath are used to calculate the digest.
Resolve runtimeClasspath: The implicit task dependency on :library:jar task is lost here when the configuration is resolved prior to task execution. The lib project will not be built when the :app:badClasspathPrinter task is run, leading to a failure in calculateDigest because the lib.jar file will not exist.

Do This Instead

To avoid issues, always defer resolution to the execution phase by using lazy APIs like FileCollection.

build.gradle.kts

dependencies {
    runtimeOnly(project(":lib")) // (1)
}

abstract class GoodClasspathPrinter : DefaultTask() {
    @get:InputFiles
    abstract val classpath: ConfigurableFileCollection // (2)

    private fun calculateDigest(fileOrDirectory: File): Int {
        require(fileOrDirectory.exists()) { "File or directory $fileOrDirectory doesn't exist" }
        return 0 // actual implementation is stripped
    }

    @TaskAction
    fun run() {
        logger.lifecycle(
            classpath.joinToString("\n") {
                val digest = calculateDigest(it) // (3)
                "$it#$digest"
            }
        )
    }
}

tasks.register("goodClasspathPrinter", GoodClasspathPrinter::class.java) {
    classpath.from(configurations.named("runtimeClasspath")) // (4)
}

build.gradle

dependencies {
    runtimeOnly(project(":lib")) // (1)
}

abstract class GoodClasspathPrinter extends DefaultTask {

    @InputFiles
    abstract ConfigurableFileCollection getClasspath() // (2)

    protected int calculateDigest(File fileOrDirectory) {
        if (!fileOrDirectory.exists()) {
            throw new IllegalArgumentException("File or directory $fileOrDirectory doesn't exist")
        }
        return 0 // actual implementation is stripped
    }

    @TaskAction
    void run() {
        logger.lifecycle(
            classpath.collect { file ->
                def digest = calculateDigest(file) // (3)
                "$file#$digest"
            }.join("\n")
        )
    }
}

tasks.register("goodClasspathPrinter", GoodClasspathPrinter) {
    classpath.from(configurations.named("runtimeClasspath")) // (4)
}

Write to a file in the output directory: This is the same.
Declare input files property as ConfigurableFileCollection: This lazy collection type will track task dependencies.
Dependency artifacts are resolved to calculate digest: The classpath will be resolved at execution time to calculate the digest.
Configuration is passed to input property directly: Using from causes the configuration to be lazily wired to the input property. The configuration will be resolved when necessary, preserving task dependencies. The output reveals that the lib project is now built when the :app:goodClasspathPrinter task is run because of the implicit task dependency, and the lib.jar file is found when calculating the digest.

Tags

#tasks, #inputs-and-outputs, #configurations

Use `@PathSensitivity.NONE` for file inputs and `@PathSensitivity.RELATIVE` for directories

Use @PathSensitivity.NONE for file inputs and @PathSensitivity.RELATIVE for directory inputs.

Explanation

Tasks should generally care about the contents of their input files, not their location on disk.

When annotating file-based input properties (for example, @InputFile or @InputFiles collections), use @PathSensitivity.NONE. This tells Gradle to ignore the path and only consider the file contents when determining whether a task is up-to-date.

For directory-based inputs (for example, @InputDirectory or @InputFiles collections), use @PathSensitivity.RELATIVE. This tells Gradle to also consider only the name of the directory (ignoring its absolute location) and to relativize the paths of all files within that directory to it when doing up-to-date checks.

Using PathSensitivity.NAME_ONLY or @PathSensitivity.ABSOLUTE is generally incorrect.

PathSensitivity.NAME_ONLY tells Gradle to consider a file’s name in addition to its contents, which is rarely useful.

@PathSensitivity.ABSOLUTE tells Gradle to consider a file’s complete absolute path. This prevents Build Cache and Configuration Cache hits across different machines or checkout locations, making your build non-relocatable. It can also lead to confusing behavior where the same build produces different task outcomes when run from different directories. If no @PathSensitive annotation is provided, PathSensitivity.ABSOLUTE is the default.

Example

Don’t Do This

build.gradle.kts

abstract class AnimalSearchTask : DefaultTask() {
    @get:Input
    abstract val find: Property<String>

    @get:InputFile
    @get:PathSensitive(PathSensitivity.ABSOLUTE) // (1)
    abstract val candidatesFile: RegularFileProperty

    @get:OutputFile
    abstract val resultsFile: RegularFileProperty

    @TaskAction
    fun search() {
        if (candidatesFile.get().getAsFile().readLines().contains(find.get())) {
            val msg = "Found a " + find.get() + "!"
            getLogger().lifecycle(msg)
            resultsFile.get().asFile.writeText(msg)
        }
    }
}

val useAlternateInput = providers.gradleProperty("useAlternateInput").isPresent()

val copyTask = tasks.register<Copy>("copy") {
    from(layout.projectDirectory.file("candidates.txt"))
    destinationDir = (if (useAlternateInput) { layout.buildDirectory.dir("alternateSearchInput") } else { layout.buildDirectory.dir("searchInput") }).get().asFile
}

tasks.register<AnimalSearchTask>("search") {
    find = "cat"
    candidatesFile.fileProvider(copyTask.map { File(it.destinationDir, "candidates.txt") })
    resultsFile = layout.buildDirectory.file("searchOutput/results.txt")
    dependsOn(copyTask)
}

build.gradle

abstract class AnimalSearchTask extends DefaultTask {
    @Input
    abstract Property<String> getFind()

    @InputFile
    @PathSensitive(PathSensitivity.ABSOLUTE) // (1)
    abstract RegularFileProperty getCandidatesFile()

    @OutputFile
    abstract RegularFileProperty getResultsFile()

    @TaskAction
    void search() {
        if (candidatesFile.get().getAsFile().readLines().contains(find.get())) {
            def msg = "Found a " + find.get() + "!"
            getLogger().lifecycle(msg)
            resultsFile.get().asFile.text = msg
        }
    }
}

def useAlternateInput = providers.gradleProperty("useAlternateInput").isPresent()

def copyTask = tasks.register("copy", Copy) {
    from(layout.projectDirectory.file("candidates.txt"))
    destinationDir = (useAlternateInput ? layout.buildDirectory.dir("alternateSearchInput") : layout.buildDirectory.dir("searchInput")).get().asFile // (2)
}

tasks.register("search", AnimalSearchTask) {
    find = "cat"
    candidatesFile.fileProvider(copyTask.map { new File(it.destinationDir, "candidates.txt") }) // (3)
    resultsFile = layout.buildDirectory.file("searchOutput/results.txt")
    dependsOn(copyTask)
}

The AnimalSearchTask task type uses a file input property annotated with @PathSensitivity.ABSOLUTE. This means that the absolute path of the input file is used to determine if the task is UP-TO-DATE or if it can be loaded from cache. Yet the path is irrelevant for the operation of the task’s @TaskAction, which only cares about file contents.
The copy task will move the exact same candidates.txt to different destination directories, depending on if the useAlternateInput project property is set.
The search task is wired to use as input whatever the file the copy task moved to its destinationDir. Despite the contents of the file being the same, when enabling the -PuseAlternateInput after a successful build, the search task will be out-of-date due to its different directory, and the search will be rerun.

Do this Instead

build.gradle.kts

@get:InputFile
@get:PathSensitive(PathSensitivity.NONE) // (1)
abstract val candidatesFile: RegularFileProperty

build.gradle

@InputFile
@PathSensitive(PathSensitivity.NONE) // (1)
abstract RegularFileProperty getCandidatesFile()

Everything remains the same, except that the input property is now annotated with @PathSensitivity.NONE. Only the contents of this input file matter to this task. When the search task is rerun with -PuseAlternateInput, it remains UP-TO-DATE.

References

Input Relocatability

Tags

Use unique output files and directories

Overlapping output files or directories cause tasks to rerun unnecessarily and waste work.

Explanation

Gradle tracks all output files and directories declared by tasks to decide whether a task needs to be rerun. For example, if the contents of a task’s output directory change after its last execution, Gradle will rerun that task.

Ensuring that each task uses its own unique output files and directories, both within a project and across the entire build, prevents unnecessary work.

Example

Don’t Do This

build.gradle.kts

abstract class GreetingTask : DefaultTask() {
    @get:Input
    abstract val type: Property<String>
    @get:OutputDirectory
    abstract val outputDirectory: DirectoryProperty

    @TaskAction
    fun run() {
        val outFileName = type.get() + ".txt"
        val message = "Hello " + type.get()
        outputDirectory.file(outFileName).get().asFile.writeText(message) // (1)
    }
}

abstract class ConsumerTask : DefaultTask() {
    @get:InputDirectory
    abstract val inputDirectory: DirectoryProperty
    @get:OutputFile
    abstract val outputFile: RegularFileProperty

    @TaskAction
    fun run() {
        val message = inputDirectory.get().file("a.txt").asFile.readText() // (2)
        outputFile.get().asFile.writeText(message)
    }
}

val greeterA = tasks.register<GreetingTask>("greeterA") {
    type = "a"
    outputDirectory = layout.buildDirectory.dir("greetings") // (3)
}
tasks.register<GreetingTask>("greeterB") {
    type = "b"
    outputDirectory = layout.buildDirectory.dir("greetings") // (4)
}

tasks.register<ConsumerTask>("consumer") {
    inputDirectory = greeterA.flatMap { it.outputDirectory } // (5)
    outputFile = layout.buildDirectory.file("consumerOutput.txt")
}

build.gradle

abstract class GreetingTask extends DefaultTask {
    @Input
    abstract Property<String> getType()
    @OutputDirectory
    abstract DirectoryProperty getOutputDirectory()

    @TaskAction
    void run() {
        def outFileName = type.get() + ".txt"
        def message = "Hello " + type.get()
        outputDirectory.file(outFileName).get().asFile.text = message // (1)
    }
}

abstract class ConsumerTask extends DefaultTask {
    @InputDirectory
    abstract DirectoryProperty getInputDirectory()
    @OutputFile
    abstract RegularFileProperty getOutputFile()

    @TaskAction
    void run() {
        def message = inputDirectory.get().file("a.txt").asFile.text // (2)
        outputFile.get().asFile.write(message)
    }
}

def greeterA = tasks.register("greeterA", GreetingTask) {
    type = "a"
    outputDirectory = layout.buildDirectory.dir("greetings") // (3)
}
tasks.register("greeterB", GreetingTask) {
    type = "b"
    outputDirectory = layout.buildDirectory.dir("greetings") // (4)
}

tasks.register("consumer", ConsumerTask) {
    inputDirectory = greeterA.flatMap { it.outputDirectory } // (5)
    outputFile = layout.buildDirectory.file("consumerOutput.txt")
}

Write to a file in the output directory: This task produces a single file in the outputDirectory, named based on the type input.
Read a specific file in the input directory: This task only needs to read a single a.txt file in the input directory.
Set output directory: Sets outputDirectory to a subdirectory in buildDirectory.
Set output directory: Same as above, using the same shared greetings directory.
Wire greeterA to consumer: Makes sure that greeterA runs and produces the output directory before it is used by consumer.

With this setup, if you run the consumer task, then greeterB, the consumer task will be invalidated.

The next time consumer is run it will not be UP-TO-DATE and will have to run again despite not using the output from greeterB.

This happens because greeterB changes the contents of the shared output directory greetings, which is an output of greeterA that consumer depends on (despite consumer only actually using the unchanged a.txt file in that directory).

Do This Instead

To avoid issues, avoid using shared task output directories and files.

Instead, tasks should only declare the exact outputs and consume the exact inputs that they actually produce and consume.

The simplest change to make here is to use distinct output directories for each GreetingTask. This alone is sufficient to fix the problem.

build.gradle.kts

val greeterA = tasks.register<GreetingTask>("greeterA") {
    type = "a"
    outputDirectory = layout.buildDirectory.dir("greetings")
}
tasks.register<GreetingTask>("greeterB") {
    type = "b"
    outputDirectory = layout.buildDirectory.dir("greetings-2") // (1)
}

build.gradle

def greeterA = tasks.register("greeterA", GreetingTask) {
    type = "a"
    outputDirectory = layout.buildDirectory.dir("greetings")
}
tasks.register("greeterB", GreetingTask) {
    type = "b"
    outputDirectory = layout.buildDirectory.dir("greetings-2") // (1)
}

Set unique output directories: Each GreetingTask is assigned its own unique output directory based on the type input.

Now when running consumer task, then greeterB, then consumer task remains UP-TO-DATE as Gradle knows that it is not using the output from greeterB, since greeterA and greeterB write to distinct output directories.

However, a more complete and idiomatic approach realizes that:

Tasks that produce single output files should make this clear from the type of their @Output properties.
Tasks that only consume single input files should make this clear from the type of their @Input properties.

build.gradle.kts

abstract class GreetingTask : DefaultTask() {
    @get:Input
    abstract val type: Property<String>
    @get:OutputFile
    abstract val outputFile: RegularFileProperty // (1)

    @TaskAction
    fun run() {
        val message = "Hello " + type.get()
        outputFile.get().asFile.writeText(message)
    }
}

abstract class ConsumerTask : DefaultTask() {
    @get:InputFile
    abstract val inputFile: RegularFileProperty // (2)
    @get:OutputFile
    abstract val outputFile: RegularFileProperty

    @TaskAction
    fun run() {
        val message = inputFile.get().asFile.readText()
        outputFile.get().asFile.writeText(message)
    }
}

val greeterA = tasks.register<GreetingTask>("greeterA") {
    type = "a"
    outputFile = layout.buildDirectory.dir("greetings").map { it.file("a.txt") } // (3)
}
tasks.register<GreetingTask>("greeterB") {
    type = "b"
    outputFile = layout.buildDirectory.dir("greetings").map { it.file("b.txt") }
}

tasks.register<ConsumerTask>("consumer") {
    inputFile = greeterA.map { it.outputFile.get() } // (4)
    outputFile = layout.buildDirectory.file("consumerOutput.txt")
}

build.gradle

abstract class GreetingTask extends DefaultTask {
    @Input
    abstract Property<String> getType()
    @OutputFile
    abstract RegularFileProperty getOutputFile() // (1)

    @TaskAction
    void run() {
        def message = "Hello " + type.get()
        outputFile.get().asFile.text = message
    }
}

abstract class ConsumerTask extends DefaultTask {
    @InputFile
    abstract RegularFileProperty getInputFile() // (2)
    @OutputFile
    abstract RegularFileProperty getOutputFile()

    @TaskAction
    void run() {
        def message = inputFile.get().asFile.text
        outputFile.get().asFile.write(message)
    }
}

def greeterA = tasks.register("greeterA", GreetingTask) {
    type = "a"
    outputFile = layout.buildDirectory.dir("greetings").map { it.file("a.txt") } // (3)
}
tasks.register("greeterB", GreetingTask) {
    type = "b"
    outputFile = layout.buildDirectory.dir("greetings").map { it.file("b.txt") }
}

tasks.register("consumer", ConsumerTask) {
    inputFile = greeterA.map { it.outputFile.get() } // (4)
    outputFile = layout.buildDirectory.file("consumerOutput.txt")
}

Write to a specific output file: This task produces a single file to a directly specified outputFile without registering an entire output directory.
Read a specific file: Unlike the previous example the input is a single directly specified inputFile file.
Set output file: Sets outputFile to a file that is inside a shared subdirectory of buildDirectory.
Wire greeterA to consumer: Makes sure that greeterA produces the output file before it is used by consumer by wiring task inputs to outputs directly.

Now when running consumer task, then greeterB, the consumer task remains UP-TO-DATE as Gradle knows that it is not using the output from greeterB, since greeterA and greeterB produce and consume distinct files (that happen to be in created in the same directory).

Tags

Don’t hardcode Task names unless they are documented as Public API

Hardcoding task names can make a build fragile when upgrading Gradle or third-party plugins.

Explanation

Some task names in Gradle are part of the Gradle public API and are stable. Most other task names in Gradle and third-party plugins are internal implementation details. They may be renamed or removed in future versions and should not be relied upon. Task types are also not guaranteed to remain stable; plugin authors may refactor them.

In practice, configuring tasks by type is usually more robust than depending on specific names, especially in ecosystems like Android or Kotlin where many tasks are generated dynamically.

Prefer, in order:

Plugin DSL - Configure tasks via extension blocks provided by a plugin that are automatically wired to the tasks that plugin creates. This is the most future-proof and stable option.
Task types - More robust than names in many cases, but can still change across plugin versions, depending on the plugin’s backwards compatibility policies.
Task names - Use only when they are explicitly documented as public API.

As a plugin author, provide a DSL extension for users to configure behavior declaratively. Internally wire the configuration into your tasks. Avoid exposing task names as part of your public API unless you are prepared to maintain them with deprecation cycles.

Example

Don’t Do This

build.gradle.kts

plugins {
    id("java-library")
    id("maven-publish")
}

tasks.named<JavaCompile>("compileJava").configure { // (1)
    sourceCompatibility = "17"
    targetCompatibility = "17"
}

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

tasks.named<GenerateMavenPom>("generatePomFileForMavenPublication").configure { // (2)
    pom.url = "sample.gradle.org"
}

build.gradle

plugins {
    id("java-library")
    id("maven-publish")
}

tasks.named("compileJava") { // (1)
    sourceCompatibility = "17"
    targetCompatibility = "17"
}

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

tasks.named("generatePomFileForMavenPublication") { // (2)
    pom.url = "sample.gradle.org"
}

Looking up compileJava by name: This relies on the hardcoded "compileJava" string.
Using tasks.named to get the generatePomFileForMavenPublication task: This unnecessarily relies on this task’s name, even though it’s the only GenerateMavenPom task that needs configuring.

Do This Instead

A better option for the compileJava configuration is to use a public constant — this task name is part of public API, so referencing it via the constant is safe:

build.gradle.kts

tasks.named<JavaCompile>(JavaPlugin.COMPILE_JAVA_TASK_NAME) { // (1)
    sourceCompatibility = "17"
    targetCompatibility = "17"
}

build.gradle

tasks.named(JavaPlugin.COMPILE_JAVA_TASK_NAME) { // (1)
    sourceCompatibility = "17"
    targetCompatibility = "17"
}

Using tasks.named with JavaPlugin.COMPILE_JAVA_TASK_NAME: Replaces the hardcoded string with a public constant.

The best option is to use the plugin DSL where possible — this avoids referring to tasks by name or type at all:

build.gradle.kts

java { // (1)
    setSourceCompatibility(JavaVersion.VERSION_17)
}

publishing {
    publications {
        create<MavenPublication>("maven") {
            from(components["java"])
            pom.url = "sample.gradle.org" // (2)
        }
    }
}

build.gradle

java { // (1)
    setSourceCompatibility(JavaVersion.VERSION_17)
}

publishing {
    publications {
        maven(MavenPublication) {
            from(components.java)
            pom.url = "sample.gradle.org" // (2)
        }
    }
}

Using Java DSL: Entirely avoids implementation details of java-library plugin and sets sourceCompatibility for all JavaCompile tasks.
Using publishing DSL: Avoids hardcoding task names and ensures that the generated POM has the expected URL.

Tags

#tasks, #upgrades

Don’t access a `Project` instance during Task Execution

Do not access a Project instance inside a task action or task property.

Explanation

Accessing the Project instance during task execution is not compatible with the Configuration Cache and should be avoided. Alternatives exist for almost every use case involving data or operations from the Project object:

Specify the data you were previously retrieving from the Project instance as an explicit task input.
Use similar functionality already exposed through the Task object (e.g., Task.getLogger() instead of Project.getLogger()).
Capture Project values in a local variable during task configuration, which can then be referenced during execution.

Note	Accessing the `Project` instance during task configuration is expected and safe — this is how you wire task input properties to project properties. The problem arises when `Project` is accessed during task execution (e.g., inside `@TaskAction` or `doLast`).

Example

Don’t Do This

build.gradle.kts

abstract class VersionTask : DefaultTask() {

    @get:OutputDirectory
    abstract val outputDirectory: DirectoryProperty

    @TaskAction
    fun run() {
        val outputFile = outputDirectory.file("build_version.txt")
        outputFile.get().asFile.writeText(project.version.toString()) // (1)
    }
}

tasks.register<VersionTask>("generateVersionFile") {
    outputDirectory.set(project.layout.buildDirectory)
}

build.gradle

abstract class VersionTask extends DefaultTask {

    @OutputDirectory
    abstract DirectoryProperty getOutputDirectory()

    @TaskAction
    void run() {
        def outputFile = outputDirectory.file("build_version.txt")
        outputFile.get().asFile.text = project.version.toString() // (1)
    }
}

tasks.register("generateVersionFile", VersionTask) {
    outputDirectory = project.layout.buildDirectory
}

Reading project.version in a task action: Inside the task’s action, the Project instance is accessed to read the version property.

There are two main problems with this setup:

Accessing the Project instance during task execution will cause Configuration Cache failures.
Because the version is not declared as a task input, Gradle cannot track it. This leads to incorrect up-to-date results if the project version changes.

Do This Instead

To ensure compatibility, avoid accessing the Project instance during task execution. Instead, tasks should explicitly declare all required inputs.

build.gradle.kts

abstract class VersionTask : DefaultTask() {
    @get:Input
    abstract val version: Property<String> // (1)

    @get:OutputDirectory
    abstract val outputDirectory: DirectoryProperty

    @TaskAction
    fun run() {
        outputDirectory.file("build_version.txt").get().asFile.writeText(version.get())
    }
}

tasks.register<VersionTask>("generateVersionFile") {
    version.set(project.version.toString()) // (2)
    outputDirectory.set(project.layout.buildDirectory.dir("build-info")) // (3)
}

build.gradle

abstract class VersionTask extends DefaultTask {
    @Input
    abstract Property<String> getVersion() // (1)

    @OutputDirectory
    abstract DirectoryProperty getOutputDirectory()

    @TaskAction
    void run() {
        outputDirectory.file("build_version.txt").get().asFile.text = version.get()
    }
}

tasks.register("generateVersionFile", VersionTask) {
    version = project.version // (2)
    outputDirectory = project.layout.buildDirectory.dir("build-info") // (3)
}

Declare the version as an input property: This allows Gradle to track the version string for up-to-date checks.
Assign the version during configuration: It is safe to read project.version during the configuration phase to assign it to a task input.
Set the output location: Use project.layout during configuration to define the task’s output directory.

Now, when running the task, there are no "hidden inputs" that Gradle cannot track. This ensures that up-to-date checks accurately determine when a task needs to run again. Additionally, because the Project object is not accessed after configuration, the Configuration Cache will function correctly.

References

Configuration Cache Requirements

Tags

#properties, #wrapper

Wire lazy task outputs using `map` and `flatMap`

Use flatMap to extract a Provider-typed output from a task, and map to transform the resulting value. Together, they preserve the task dependency chain so Gradle knows which tasks must run first.

Explanation

When wiring task outputs to inputs, flatMap extracts a Provider-typed output from a task while preserving the task dependency that the output Provider carries. Then map transforms that value. For example, reading a file’s contents or extracting a path, without breaking the chain. The typical pattern looks like:

consumer.inputContent.set(
    producer.flatMap { it.outputFile }       // extract the Provider, keeping the task dependency
        .map { it.asFile.readText() }        // transform the value lazily at execution time
)

consumer.inputContent.set(
    producer.flatMap { it.outputFile }       // extract the Provider, keeping the task dependency
        .map { it.asFile.text }              // transform the value lazily at execution time
)

For dependency tracking to work, task outputs should be directly annotated abstract getters:

@get:OutputFile
abstract val outputFile: RegularFileProperty

@OutputFile
abstract RegularFileProperty getOutputFile()

With this pattern, flatMap reliably carries the task dependency and map safely transforms the result.

A few specific patterns break this chain:

Do not call .get() inside map or flatMap — the file doesn’t exist yet at configuration time, breaking lazy configuration and task dependency tracking
Do not use standalone provider {} to wrap task outputs — provider {} produces a disconnected provider with no task dependency information
Use directly annotated abstract getters for task outputs — flatMap can only track dependencies through directly annotated abstract getters, not task outputs that exist only to define transforms of other properties. Getters that return Provider instead of Property also break tracking, even when annotated.
Use map for plain values, flatMap for Provider-typed outputs — flatMap requires its closure to return a Provider; use map to extract File or String values

1. Do not call `.get()` inside `map` or `flatMap`

Calling .get() inside map to read file content fails because the file does not exist yet at configuration time — the producer task has not run. This pattern also breaks the Configuration Cache.

Both examples below use the same generatorTask producer; only the consumer differs.

Don’t Do This

build.gradle.kts

val generatorTask = tasks.register<GeneratorTask>("generator") {
    outputFile.set(layout.buildDirectory.file("eager-output.txt"))
}

tasks.register<ConsumerTask>("consumeEager") {
    inputFile.set(generatorTask.flatMap { it.outputFile })
    inputContent.set(generatorTask.map {
        it.outputFile.get().asFile.readText() // (1)
    })
}

build.gradle

def generatorTask = tasks.register('generator', GeneratorTask) {
    outputFile = layout.buildDirectory.file('eager-output.txt')
}

tasks.register('consumeEager', ConsumerTask) {
    inputFile = generatorTask.flatMap { it.outputFile }
    inputContent = generatorTask.map {
        it.outputFile.get().asFile.text // (1)
    }
}

File read at configuration time: .get() realizes the file before the producer task has run; reading it here fails because the file doesn’t exist yet.

Do This Instead

Use the flatMap/map chain instead. The map on a flatMap result is evaluated lazily at execution time, when the file exists:

build.gradle.kts

val generatorTask = tasks.register<GeneratorTask>("generator") {
    outputFile.set(layout.buildDirectory.file("output.txt"))
}

tasks.register<ConsumerTask>("consumeLazy") {
    inputFile.set(generatorTask.flatMap { it.outputFile }) // (1)
    inputContent.set(
        generatorTask.flatMap { it.outputFile }
            .map { it.asFile.readText() } // (2)
    )
}

build.gradle

def generatorTask = tasks.register('generator', GeneratorTask) {
    outputFile = layout.buildDirectory.file('output.txt')
}

tasks.register('consumeLazy', ConsumerTask) {
    inputFile = generatorTask.flatMap { it.outputFile } // (1)
    inputContent = generatorTask.flatMap { it.outputFile }
        .map { it.asFile.text } // (2)
}

Lazy wiring via flatMap: extracts the outputFile Provider while preserving the dependency on generator.
Read content lazily: chaining map on the flatMap result defers reading until execution time.

This preserves the task dependency because the provider chain remains connected to the original task.

2. Do not use standalone `provider {}` to wrap task outputs

A standalone provider {} creates a provider with no connection to any task. Gradle cannot determine that it depends on the producer task, so the producer will not be added to the task graph.

Both examples below use the same generatorTask producer; only the consumer differs.

Don’t Do This

build.gradle.kts

val generatorTask = tasks.register<GeneratorTask>("generator") {
    outputFile.set(layout.buildDirectory.file("output.txt"))
}

tasks.register<ConsumerTask>("consumeNaked") {
    inputFile.set(generatorTask.flatMap { it.outputFile })
    inputContent.set(provider { // (1)
        generatorTask.get().outputFile.get().asFile.readText()
    })
}

build.gradle

def generatorTask = tasks.register('generator', GeneratorTask) {
    outputFile = layout.buildDirectory.file('output.txt')
}

tasks.register('consumeNaked', ConsumerTask) {
    inputFile = generatorTask.flatMap { it.outputFile }
    inputContent = providers.provider { // (1)
        generatorTask.get().outputFile.get().asFile.text
    }
}

Disconnected provider {} block: has no link to the generator task; Gradle cannot infer that consumeNaked depends on generator from this provider alone.

Do This Instead

Use flatMap to extract the Provider-typed output, then chain map to transform the value:

build.gradle.kts

val generatorTask = tasks.register<GeneratorTask>("generator") {
    outputFile.set(layout.buildDirectory.file("output.txt"))
}

tasks.register<ConsumerTask>("consumeLazy") {
    inputFile.set(generatorTask.flatMap { it.outputFile }) // (1)
    inputContent.set(
        generatorTask.flatMap { it.outputFile }
            .map { it.asFile.readText() } // (2)
    )
}

build.gradle

def generatorTask = tasks.register('generator', GeneratorTask) {
    outputFile = layout.buildDirectory.file('output.txt')
}

tasks.register('consumeLazy', ConsumerTask) {
    inputFile = generatorTask.flatMap { it.outputFile } // (1)
    inputContent = generatorTask.flatMap { it.outputFile }
        .map { it.asFile.text } // (2)
}

Lazy wiring via flatMap: extracts the outputFile Provider while preserving the dependency on generator.
Read content lazily: chaining map on the flatMap result defers reading until execution time.

3. Use directly annotated abstract getters for task outputs

When a task’s output is computed via .map {} rather than directly annotated with @OutputFile, flatMap may extract the mapped provider without preserving the task dependency.

Don’t Do This

build.gradle.kts

abstract class ProducerTask @Inject constructor(
    objectFactory: ObjectFactory
) : DefaultTask() {
    @get:Internal
    val someDirectory = objectFactory.directoryProperty()

    // This property is DERIVED via map - not directly annotated
    @get:OutputFile
    val outputFile = someDirectory.map { it.file("output.txt") }

    @TaskAction
    fun execute() {
        outputFile.get().asFile.writeText("content")
    }
}

val derivedProducer = tasks.register<ProducerTask>("produceDerived") {
    someDirectory.set(layout.buildDirectory.dir("output"))
}

tasks.register<Sync>("consumeDerived") {
    from(derivedProducer.flatMap { it.outputFile }) // (1)
    into(layout.buildDirectory.dir("sync"))
}

build.gradle

abstract class ProducerTask extends DefaultTask {
    @Internal
    abstract DirectoryProperty getSomeDirectory()

    // This property is DERIVED via map - not directly annotated
    @OutputFile
    Provider<RegularFile> getOutputFile() {
        return someDirectory.map { it.file('output.txt') }
    }

    @TaskAction
    void execute() {
        outputFile.get().asFile.text = 'content'
    }
}

def derivedProducer = tasks.register('produceDerived', ProducerTask) {
    someDirectory = layout.buildDirectory.dir('output')
}

tasks.register('consumeDerived', Sync) {
    from(derivedProducer.flatMap { it.outputFile }) // (1)
    into(layout.buildDirectory.dir('sync'))
}

Derived output property: when outputFile is built via .map { … } rather than annotated directly, flatMap may lose the task dependency.

Do This Instead

As a workaround, use .map { it.property.get() } to preserve the dependency:

build.gradle.kts

abstract class ProducerTask @Inject constructor(
    objectFactory: ObjectFactory
) : DefaultTask() {
    @get:Internal
    val someDirectory = objectFactory.directoryProperty()

    @get:OutputFile
    val outputFile = someDirectory.map { it.file("output.txt") }

    @TaskAction
    fun execute() {
        outputFile.get().asFile.writeText("content")
    }
}

val derivedProducer = tasks.register<ProducerTask>("produceDerived") {
    someDirectory.set(layout.buildDirectory.dir("output"))
}

tasks.register<Sync>("consumeDerivedSync") {
    from(derivedProducer.map { it.outputFile.get() }) // (1)
    into(layout.buildDirectory.dir("sync"))
}

build.gradle

abstract class ProducerTask extends DefaultTask {
    @Internal
    abstract DirectoryProperty getSomeDirectory()

    @OutputFile
    Provider<RegularFile> getOutputFile() {
        return someDirectory.map { it.file('output.txt') }
    }

    @TaskAction
    void execute() {
        outputFile.get().asFile.text = 'content'
    }
}

def derivedProducer = tasks.register('produceDerived', ProducerTask) {
    someDirectory = layout.buildDirectory.dir('output')
}

tasks.register('consumeDerivedSync', Sync) {
    from(derivedProducer.map { it.outputFile.get() }) // (1)
    into(layout.buildDirectory.dir('sync'))
}

Workaround with .map { it.property.get() }: preserves the task dependency at the cost of an explicit .get() call.

The preferred approach is to use directly annotated abstract getters instead of derived ones, so that flatMap works reliably:

build.gradle.kts

abstract class DirectProducerTask : DefaultTask() {
    // Directly annotated property - not derived
    @get:OutputFile
    abstract val outputFile: RegularFileProperty

    @TaskAction
    fun execute() {
        outputFile.get().asFile.writeText("content")
    }
}

val directProducer = tasks.register<DirectProducerTask>("directProducer") {
    outputFile.set(layout.buildDirectory.file("output/output.txt"))
}

tasks.register<Sync>("consumeDirect") {
    from(directProducer.flatMap { it.outputFile }) // (1)
    into(layout.buildDirectory.dir("sync-direct"))
}

build.gradle

abstract class DirectProducerTask extends DefaultTask {
    // Directly annotated property - not derived
    @OutputFile
    abstract RegularFileProperty getOutputFile()

    @TaskAction
    void execute() {
        outputFile.get().asFile.text = 'content'
    }
}

def directProducer = tasks.register('directProducer', DirectProducerTask) {
    outputFile = layout.buildDirectory.file('output/output.txt')
}

tasks.register('consumeDirect', Sync) {
    from(directProducer.flatMap { it.outputFile }) // (1)
    into(layout.buildDirectory.dir('sync-direct'))
}

Directly annotated abstract getter: with @OutputFile on an abstract RegularFileProperty, flatMap carries the task dependency reliably.

4. Use `map` for plain values, `flatMap` for `Provider`-typed outputs

When a task uses old-style getters (like File) instead of Provider-typed outputs, use map instead of flatMap to extract the value. The flatMap closure must return a Provider; wrapping a plain value in a standalone provider {} would compile, but — as in item 2 — it would drop the task dependency.

Do This

build.gradle.kts

abstract class LegacyTask : DefaultTask() {
    // Old-style eager property (before Provider API)
    @get:OutputDirectory
    lateinit var destinationDir: File

    @TaskAction
    fun execute() {
        destinationDir.mkdirs()
        File(destinationDir, "output.txt").writeText("content")
    }
}

val legacy = tasks.register<LegacyTask>("legacy") {
    destinationDir = layout.buildDirectory.dir("docs").get().asFile
}

tasks.register<ConsumerTask>("consumeLegacy") {
    inputFile.fileProvider(legacy.map { File(it.destinationDir, "output.txt") }) // (1)
    inputContent.set(legacy.map { File(it.destinationDir, "output.txt").readText() })
}

build.gradle

abstract class LegacyTask extends DefaultTask {
    // Old-style eager property (before Provider API)
    @OutputDirectory
    File destinationDir

    @TaskAction
    void execute() {
        destinationDir.mkdirs()
        new File(destinationDir, 'output.txt').text = 'content'
    }
}

def legacy = tasks.register('legacy', LegacyTask) {
    destinationDir = layout.buildDirectory.dir('docs').get().asFile
}

tasks.register('consumeLegacy', ConsumerTask) {
    inputFile.fileProvider(legacy.map { new File(it.destinationDir, 'output.txt') }) // (1)
    inputContent = legacy.map { new File(it.destinationDir, 'output.txt').text }
}

Use map for non-Provider outputs: when the producer exposes a plain File instead of a Provider, map is the right extractor.

References

Working with task inputs and outputs

Tags

#tasks, #task-configuration-avoidance

Best Practices for Performance

Prefer the `-bin` Gradle Distribution

Gradle publishes two distribution variants for each release: -bin (binaries only) and -all (binaries, sources, and documentation). For most builds, you should prefer the smaller -bin distribution.

Using -bin reduces download size and verification effort, speeds up CI and developer builds, and limits the number of artifacts you need to trust.

Explanation

Each Gradle release provides:

gradle-<version>-bin.zip – binaries only
gradle-<version>-all.zip – binaries plus sources and offline documentation

In modern setups:

IDEs and build tools can download sources and documentation directly from repositories or online docs (even when using -bin releases).
The -all distribution is rarely required outside of specific offline or air-gapped environments.

Preferring -bin helps because:

It reduces download and cache size for CI and local builds.
There is less to verify and fewer artifacts to trust (one smaller archive instead of a larger “everything included” zip).
It shortens the feedback loop when upgrading Gradle.

In special cases (for example, fully offline environments), you can still use -all, but it should be a conscious exception rather than the default.

Don’t Do This

Make sure your Wrapper doesn’t point to the -all distribution:

gradle/wrapper/gradle-wrapper.properties:

distributionUrl=https\://services.gradle.org/distributions/gradle-<version>-all.zip

Do This Instead

Configure the Wrapper to use the -bin distribution:

gradle/wrapper/gradle-wrapper.properties:

distributionUrl=https\://services.gradle.org/distributions/gradle-<version>-bin.zip

References

Gradle Wrapper checksum verification

Tags

#upgrades, #wrapper

Use UTF-8 File Encoding

Set UTF-8 as the default file encoding to ensure consistent behavior across platforms.

Explanation

Use UTF-8 as the default file encoding to ensure consistent behavior across environments and avoid caching issues caused by platform-dependent default encodings.

This is especially important when working with build caching, since differences in file encoding between environments can cause unexpected cache misses.

To enforce UTF-8 encoding, add the following to your gradle.properties file:

org.gradle.jvmargs=-Dfile.encoding=UTF-8

Note	Do not rely on the default encoding of the underlying JVM or operating system, as this may differ between environments and lead to inconsistent behavior.

References

File encoding and Caching.

Tags

#properties, #caching

Use the Build Cache

Use the Build Cache to save time by reusing outputs produced by previous builds.

Explanation

The Build Cache avoids re-executing tasks when their inputs haven’t changed by reusing outputs from previous builds.

This prevents redundant work. If the inputs are the same, the outputs will be too, resulting in faster, more efficient builds.

Example

Don’t Do This

Build caching is disabled by default:

gradle.properties

# caching is off by default
# org.gradle.caching=false

Do This Instead

To enable the Build Cache, add the following to your gradle.properties file:

gradle.properties

org.gradle.caching=true

When you build your project for the first time, Gradle populates the cache with the outputs of tasks like compilation.

Even if you run ./gradlew clean to delete the build directory, Gradle can reuse cached outputs in subsequent builds.

$ ./gradlew clean

:clean
BUILD SUCCESSFUL

On subsequent builds, instead of executing the :compileJava task again, the outputs of the task will be loaded from the Build Cache:

$ ./gradlew compileJava

> Task :compileJava FROM-CACHE

BUILD SUCCESSFUL in 0s
1 actionable task: 1 from cache

References

Build Cache Overview

Tags

#properties, #caching

Use the Configuration Cache

Use the Configuration Cache to significantly improve build performance by caching the result of the configuration phase and reusing it in subsequent builds.

Explanation

The Configuration Cache works by saving the result of the configuration phase. On the next build, if nothing relevant has changed, Gradle skips configuration entirely and loads the cached task graph from disk, jumping straight to task execution.

This can dramatically reduce build time for large builds, but it’s just as valuable for smaller builds where configuration overhead can dominate short iterations. Faster feedback helps developers stay focused, without waiting on redundant configuration work.

It’s important to understand how this differs from the Build Cache. The Build Cache stores the outputs of task execution, while the Configuration Cache stores the configured task graph before execution begins. These are independent mechanisms that solve different problems, but they are designed to work together for optimal performance.

Note

The Configuration Cache is the preferred way to execute Gradle builds, but it is not enabled by default. Many existing builds and plugins are not yet fully compatible, and adopting it may involve refactoring of build logic. Enabling it by default could lead to unexpected build failures, so Gradle uses an opt-in adoption model to allow teams to verify compatibility and adopt configuration caching incrementally and safely.

Example

Don’t Do This

Configuration Caching is not enabled by default:

gradle.properties

# caching is off by default
# org.gradle.configuration-cache=false

Do This Instead

To enable the Configuration Cache, add the following to your gradle.properties file:

gradle.properties

org.gradle.configuration-cache=true

When you build your project for the first time, Gradle stores the outcome of the configuration phase, including the task graph, in the Configuration Cache.

$ ./gradlew compileJava

Configuration cache entry stored.
> Task :processResources NO-SOURCE
> Task :processTestResources NO-SOURCE
> Task :compileJava
> Task :classes
> Task :compileTestJava NO-SOURCE
> Task :testClasses UP-TO-DATE
> Task :test NO-SOURCE
> Task :check UP-TO-DATE
> Task :jar
> Task :assemble
> Task :build

BUILD SUCCESSFUL in 0s
2 actionable tasks: 2 executed

On subsequent builds, instead of reconfiguring tasks like :compileJava, Gradle loads the task graph from the Configuration Cache and proceeds directly to execution.

$ ./gradlew compileJava

Configuration cache entry reused.
> Task :processResources NO-SOURCE
> Task :processTestResources NO-SOURCE
> Task :compileJava
> Task :classes
> Task :compileTestJava NO-SOURCE
> Task :testClasses UP-TO-DATE
> Task :test NO-SOURCE
> Task :check UP-TO-DATE
> Task :jar
> Task :assemble
> Task :build

BUILD SUCCESSFUL in 0s
2 actionable tasks: 2 executed

References

Enabling The Configuration Cache

Tags

#properties, #caching

Avoid Expensive Computations in Configuration Phase

Avoid expensive computations in the configuration phase, instead, move them to task actions.

Explanation

In order for Gradle to execute tasks it first needs to build the project task graph. As part of discovering what tasks to include in the task graph, Gradle will configure all the tasks that are directly requested, any task dependencies of the requested tasks, and also any tasks that are not lazily registered. This work is done in the configuration phase.

Performing expensive or slow operations such as file or network I/O, or CPU-heavy calculations in the configuration phase forces these to run even when they might be unnecessary to complete the requested work of the invoked tasks. It is better to move these operations to task actions so that they run only when required.

Example

Don’t Do This

build.gradle.kts

abstract class MyTask : DefaultTask() {
    @get:Input
    lateinit var computationResult: String
    @TaskAction
    fun run() {
        logger.lifecycle(computationResult)
    }
}

fun heavyWork(): String {
    println("Start heavy work")
    Thread.sleep(5000)
    println("Finish heavy work")
    return "Heavy computation result"
}

tasks.register<MyTask>("myTask") {
    computationResult = heavyWork() // (1)
}

build.gradle

abstract class MyTask extends DefaultTask {
    @Input
    String computationResult
    @TaskAction
    void run() {
        logger.lifecycle(computationResult)
    }
}

String heavyWork() {
    logger.lifecycle("Start heavy work")
    Thread.sleep(5000)
    logger.lifecycle("Finish heavy work")
    return "Heavy computation result"
}

tasks.register("myTask", MyTask) {
    computationResult = heavyWork() // (1)
}

Performing heavy computation during configuration phase.

Do This Instead

build.gradle.kts

abstract class MyTask : DefaultTask() {
    @TaskAction
    fun run() {
        logger.lifecycle(heavyWork()) // (1)
    }

    fun heavyWork(): String {
        logger.lifecycle("Start heavy work")
        Thread.sleep(5000)
        logger.lifecycle("Finish heavy work")
        return "Heavy computation result"
    }
}

tasks.register<MyTask>("myTask")

build.gradle

abstract class MyTask extends DefaultTask {
    @TaskAction
    void run() {
        logger.lifecycle(heavyWork()) // (1)
    }
    String heavyWork() {
        logger.lifecycle("Start heavy work")
        Thread.sleep(5000)
        logger.lifecycle("Finish heavy work")
        return "Heavy computation result"
    }
}

tasks.register("myTask", MyTask)

Performing heavy computation during execution phase in a task action.

References

Tags

#tasks

Best Practices for Security

Validate the Gradle Distribution SHA-256 Checksum

Set distributionSha256Sum in gradle-wrapper.properties to verify the integrity of the downloaded Gradle distribution.

Explanation

Always set the distributionSha256Sum property in your gradle-wrapper.properties file to verify the integrity of the downloaded Gradle distribution. This ensures the gradle-X.X-bin.zip file matches the official SHA-256 checksum published by Gradle, protecting your build from corruption or tampering.

distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip
distributionSha256Sum=2b3f4...sha256-here...f4511

This validation step enhances security by preventing the execution of compromised or incomplete Gradle distributions.

The official SHA-256 checksums can be found on the Gradle releases page.

References

Tags

Validate the Gradle Wrapper on every Upgrade

The Gradle Wrapper runs before your build logic and can deeply affect your build. You should treat any change to the Wrapper as security-sensitive.

Validate the Wrapper JAR and distribution settings every time you upgrade Gradle.

Explanation

When you update Gradle, two Wrapper files typically change:

gradle/wrapper/gradle-wrapper.jar
gradle/wrapper/gradle-wrapper.properties (distributionUrl and optionally distributionSha256Sum)

You should verify that:

The Wrapper JAR is the official binary published by Gradle (not tampered with).
The Wrapper JAR checksum matches one of the values published at gradle.org/release-checksums.
The distribution URL points to the expected Gradle release.
The distribution checksum (if configured via distributionSha256Sum) matches the release you intend to use (also listed on gradle.org/release-checksums).

Running an unverified Wrapper risks executing untrusted code before any of your build’s safeguards run.

Do this

If you use the setup-gradle action (version v4 or newer) for GitHub Actions, Wrapper validation will be performed automatically. The action validates the checksum of every gradle-wrapper.jar in your repository and fails the build if it finds any unknown Wrapper JAR.

If you use a different GitHub Actions setup, you can use the dedicated Gradle Wrapper validation action instead.

References

Tags

#wrapper

Do not Run `./gradlew` on Untrusted Projects

When working with an untrusted project, you should exercise caution before running ./gradlew.

Explanation

The gradlew (Gradle Wrapper) script is an executable that downloads and runs a specific version of Gradle. It should be generated by running the Wrapper task with a trusted Gradle installation, but there is no guarantee that a project’s authors have done this. The script or gradle-wrapper.jar could have been modified. The only way to verify this is through checksum verification.

Running an unverified wrapper is similar to running any other untrusted script from the internet. Build scripts (build.gradle, settings.gradle, etc.) can also execute arbitrary code during the configuration phase.

An unreviewed wrapper or build script could potentially access or modify files on your system, install malicious software, or compromise your environment (e.g., stealing environment variables like GITHUB_TOKEN or AWS_SECRET_KEY).

Note	Opening an untrusted project in an IDE such as IntelliJ IDEA or Android Studio will typically trigger a Gradle sync automatically, which executes build logic. Review the project’s wrapper and build scripts before opening it in your IDE.

Do this

1. Review the Build Scripts

Inspect Build Files: Look at build.gradle(.kts), settings.gradle(.kts), and gradle.properties for suspicious dependencies, plugins, custom exec tasks, or obfuscated code.

2. Verify the Gradle Wrapper Files

Checksum Verification: Use checksum validation to ensure gradle-wrapper.jar hasn’t been tampered with.
Check the URL: Open gradle/wrapper/gradle-wrapper.properties and ensure the distributionUrl points strictly to the official site: https://services.gradle.org/.
Regenerate the Wrapper: If you have a trusted Gradle installation, delete the project’s gradlew, gradlew.bat, and gradle/wrapper/gradle-wrapper.jar, then run gradle wrapper (not ./gradlew). Compare the regenerated files against the originals, any differences indicate the project’s wrapper may have been modified.

3. Work in an Isolated Environment

You can optionally run the project in a Docker container or a Virtual Machine (VM). This ensures that even if a malicious script runs, it cannot access your files.

References

Gradle Wrapper Reference

Tags

#wrapper

Build Output Should Be Byte-for-Byte Reproducible

A build is reproducible when the same source code produces byte-for-byte identical output files, on any machine, at any time.

Explanation

Reproducibility matters far beyond the publishing flow. If binaries remain identical, then downstream consumers can verify that they match the source. Build systems typically verify artifact checksums; non-determinism in artifact bytes defeats caches and deduplication logic without providing any benefit.

With this strong form of reproducibility, the question "Did my change actually change anything?" is easy to answer: compare the output hashes. Gradle’s own up-to-date checks and remote build cache also rely on stable inputs producing stable outputs.

Some common sources of non-determinism in builds are file timestamps inside archives, the order of entries inside archives, and the SDK used to compile classes. For JVM builds, keeping wall-clock timestamps on .class files inside a .jar, or letting archive entries follow the filesystem’s directory-iteration order, means that two clean builds of the same source produce slightly different artifacts with different checksums even though the output is functionally identical.

Note	Since Gradle 9.0.0, archive artifacts are set to be reproducible by default.

This is list of examples is not exhaustive. There are other ways to introduce non-reproducibility in your project. One good test to confirm reproducibility is to try re-building an older version on a different machine, and comparing the output to the published binary.

Example

Don’t Do This

build.gradle.kts

plugins {
    `java-library` // (1)
}

tasks.named<Jar>("jar") {
    isPreserveFileTimestamps = true   // (2)
    isReproducibleFileOrder = false   // (3)
}

build.gradle

plugins {
    id 'java-library' // (1)
}

tasks.named('jar', Jar) {
    preserveFileTimestamps = true   // (2)
    reproducibleFileOrder = false   // (3)
}

No java { toolchain { … } } block is declared. Gradle has no default toolchain, so the JDK used for compilation falls back to whichever JAVA_HOME is active. Different machines (and even different JDK patch releases on the same machine) emit different bytecode.
Sets preserveFileTimestamps to true, overriding the Gradle 9.0+ default of false. Every entry inside the jar is stamped with the build’s wall-clock time, so the same source produces a different jar on every build.
Sets reproducibleFileOrder to false, overriding the Gradle 9.0+ default of true. Archive entries are ordered by the filesystem’s directory-iteration order, which varies by OS and filesystem.

Do This Instead

build.gradle.kts

plugins {
    `java-library`
}

java {
    toolchain {
        // Choose your project's required version
        languageVersion = JavaLanguageVersion.of(21) // (1)
    }
}
// (2)

build.gradle

plugins {
    id 'java-library'
}

java {
    toolchain {
        // Choose your project's required version
        languageVersion = JavaLanguageVersion.of(21) // (1)
    }
}
// (2)

Pin the JDK used to compile so the build is decoupled from each developer’s local JAVA_HOME and from whichever JDK happens to be on the CI image; Gradle auto-provisions a matching JDK if one isn’t found.
Leave archive defaults alone — Gradle 9.0+ sets preserveFileTimestamps = false and reproducibleFileOrder = true on every AbstractArchiveTask (Jar, War, Ear, Zip, Tar). The performance cost of these defaults is negligible: reproducibleFileOrder adds a sort over directory listings that’s dominated by I/O and compression work, and dropping timestamps actually makes archives marginally smaller and avoids unnecessary downstream cache invalidation. If you maintain a build that still supports an older Gradle version, set both flags explicitly with tasks.withType<AbstractArchiveTask>().configureEach { … }.

References

Tags

#publishing, #tasks

Best Practices for Testing

Test your custom Task and Plugins with TestKit

You should test any custom tasks or plugins you create using Gradle TestKit.

Explanation

Gradle’s flexibility supports a natural evolution of custom types as they mature.

Creating new tasks and plugins directly in a build.gradle(.kts) file is a great way to prototype new functionality. As that functionality stabilizes, you should extract these definitions into buildSrc or a standalone plugin project for better reusability and maintainability. Once types exist outside of a single build file, you can easily write functional tests for them using TestKit.

A mature build should include functional tests for its custom types to ensure they behave as expected.

Example

Don’t Do This

The following build defines a custom task and a custom plugin that applies it within the build.gradle(.kts) file. The plugin adds multiple custom tasks that print a greeting using properties defined in a custom extension.

This is a common pattern for prototyping new functionality, but it lacks tests to verify the behavior of the custom types. The only way to verify that the task and plugin work as intended is to run the build manually and inspect the output.

build.gradle.kts

import java.time.Instant

interface MyExtension {
    val firstName: Property<String>
    val lastName: Property<String>
}

var greeter = "Hello"

@CacheableTask // (1)
abstract class MyTask: DefaultTask() {
    @get:Input
    abstract val firstName: Property<String>
    @get:Input
    abstract val lastName: Property<String>
    @get:Input
    abstract val greeting: Property<String>

    @get:OutputFile
    abstract val outputFile: RegularFileProperty

    private final val today = Instant.now() // (2)

    @TaskAction
    fun run() {
        val output = outputFile.asFile.get()
        val result = "${greeting.get()}, ${firstName.get()} ${lastName.get()}, it's currently\n$today"
        println(result)
        output.writeText(result)
    }
}

abstract class MyPlugin: Plugin<Project> {
    override fun apply(project: Project) {
        val extension = project.extensions.create("myExtension", MyExtension::class.java)

        project.tasks.register<MyTask>("task1") {
            outputFile.convention(project.layout.buildDirectory.file("output1.txt"))
        }

        project.tasks.register<MyTask>("task2") {
            outputFile.convention(project.layout.buildDirectory.file("output2.txt"))
        }

        project.tasks.withType<MyTask>().configureEach {
            group = "Custom Tasks"
            firstName.convention(extension.firstName)
            lastName.convention(extension.firstName) // (3)
            greeting.convention("Hi")
        }
    }
}

apply<MyPlugin>()

configure<MyExtension> {
    firstName = "John"
    lastName = "Smith"
}

tasks.named<MyTask>("task2") {
    greeter = "Bonjour" // (4)
}

build.gradle

import java.time.Instant

interface MyExtension {
    Property<String> getFirstName()
    Property<String> getLastName()
}

def greeter = "Hello"

@CacheableTask // (1)
abstract class MyTask extends DefaultTask {
    @Input
    abstract Property<String> getFirstName()
    @Input
    abstract Property<String> getLastName()
    @Input
    abstract Property<String> getGreeting()

    @OutputFile
    abstract RegularFileProperty getOutputFile()

    private final Instant today = Instant.now() // (2)

    @TaskAction
    void run() {
        def output = outputFile.asFile.get()
        def result = "${greeting.get()}, ${firstName.get()} ${lastName.get()}, it's currently\n$today"
        println result
        output.text = result
    }
}

abstract class MyPlugin implements Plugin<Project> {
    @Override
    void apply(Project project) {
        def extension = project.extensions.create("myExtension", MyExtension)

        project.tasks.register("task1", MyTask) { task ->
            task.outputFile.convention(project.layout.buildDirectory.file("output1.txt"))
        }

        project.tasks.register("task2", MyTask) { task ->
            task.outputFile.convention(project.layout.buildDirectory.file("output2.txt"))
        }

        project.tasks.withType(MyTask).configureEach { task ->
            task.group = "Custom Tasks"
            task.firstName.convention(extension.firstName)
            task.lastName.convention(extension.firstName) // (3)
            task.greeting.convention("Hi")
        }
    }
}

apply plugin: MyPlugin

myExtension {
    firstName = "John"
    lastName = "Smith"
}

tasks.named("task2", MyTask) {
    greeter = "Bonjour" // (4)
}

In this case, there are several problems:

The Task is declared as cacheable: However, the task’s output differs depending on when it is run, so it should not be cached.
The current time is used as an undeclared input: Inputs to a task must be explicitly declared using the appropriate annotations, otherwise Gradle cannot track changes to them.
Error in task property wiring: The lastName property is linked to the firstName property on the extension, which is likely a mistake.
The wrong variable is assigned during task configuration: The greeter variable from the buildscript is mistakenly assigned instead of the task’s greeting property.

Do This Instead

In this updated version of the build, the custom types are defined in an included build-logic composite build, which now includes a basic set of functional tests using Gradle TestKit.

While these custom types are written in Java for demonstration purposes, they could just as easily be implemented in Groovy or Kotlin. Because they reside in a separate, complete Gradle build, they can be thoroughly tested using TestKit.

├── build-logic/
│   ├── src
│   │   ├── main
│   │   │   └── java
│   │   │       └── org
│   │   │           └── example
│   │   │               └── MyExtension.java
│   │   │               └── MyPlugin.java
│   │   │               └── MyTask.java
│   │   └── functionalTest
│   │       └── java
│   │           └── org
│   │               └── example
│   │                   └── MyPluginFunctionalTest.java
│   ├── build.gradle.kts
│   └── settings.gradle.kts
├── settings.gradle.kts
└── build.gradle.kts

├── build-logic/
│   ├── src
│   │   ├── main
│   │   │   └── java
│   │   │       └── org
│   │   │           └── example
│   │   │               └── MyExtension.java
│   │   │               └── MyPlugin.java
│   │   │               └── MyTask.java
│   │   └── functionalTest
│   │       └── java
│   │           └── org
│   │               └── example
│   │                   └── MyPluginFunctionalTest.java
│   ├── build.gradle
│   └── settings.gradle
├── settings.gradle
└── build.gradle

We’ve corrected the issues with the plugin and task from the previous example:

MyTask.java

package org.example;

import org.gradle.api.DefaultTask;
import org.gradle.api.file.RegularFileProperty;
import org.gradle.api.provider.Property;
import org.gradle.api.tasks.CacheableTask;
import org.gradle.api.tasks.Input;
import org.gradle.api.tasks.InputFile;
import org.gradle.api.tasks.OutputFile;
import org.gradle.api.tasks.TaskAction;
import java.io.File;
import java.nio.file.Files;
import java.time.Instant;
import java.io.IOException;

@CacheableTask
public abstract class MyTask extends DefaultTask {
    @Input
    public abstract Property<String> getFirstName();
    @Input
    public abstract Property<String> getLastName();
    @Input
    public abstract Property<String> getGreeting();

    @OutputFile
    public abstract RegularFileProperty getOutputFile();

    @Input // (1)
    public abstract Property<Instant> getToday();

    @TaskAction
    public void run() throws IOException {
        File output = getOutputFile().getAsFile().get();
        String result = String.format("%s, %s %s, it's currently\n%s", getGreeting().get(), getFirstName().get(), getLastName().get(), getToday().get());
        System.out.println(result);
        Files.writeString(output.toPath(), result);
    }
}

Today is a proper @Input: This allows Gradle’s UP-TO-DATE checking to properly consider it when rerunning the task.

MyPlugin.java

package org.example;

import org.gradle.api.Plugin;
import org.gradle.api.Project;
import java.time.Instant;

public abstract class MyPlugin implements Plugin<Project> {
    @Override
    public void apply(Project project) {
        MyExtension extension = project.getExtensions().create("myExtension", MyExtension.class);

        project.getTasks().register("task1", MyTask.class, task -> {
            task.getOutputFile().convention(project.getLayout().getBuildDirectory().file("output1.txt"));
        });

        project.getTasks().register("task2", MyTask.class, task -> {
            task.getOutputFile().convention(project.getLayout().getBuildDirectory().file("output2.txt"));
        });

        project.getTasks().withType(MyTask.class).configureEach(task -> {
            task.setGroup("Custom Tasks");
            task.getFirstName().convention(extension.getFirstName());
            task.getLastName().convention(extension.getLastName()); // (1)
            task.getGreeting().convention("Hi");
            task.getToday().convention(Instant.now()); // (2)
        });
    }
}

Corrected typo in assignment: The last name convention set to the value of the last name from the extension.
Today is set to the same value on all tasks: Only calling Instant.now() once, rather than every time a task is created.

Writing and running the tests as described below helped identify the bugs in the plugin implementation.

We defined a functional test suite within the build-logic project. Because TestKit tests tend to be slower and more complex than unit tests, they are typically kept separate. Locating these tests in a dedicated functionalTest suite also clarifies their purpose for other developers.

build.gradle.kts

val functionalTest = testing.suites.register("functionalTest", JvmTestSuite::class) { // (1)
    useJUnitJupiter()
    dependencies {
        implementation("commons-io:commons-io:2.16.1")
        implementation(project())
        implementation(gradleTestKit()) // (2)
    }
}

tasks.check {
    dependsOn(functionalTest)
}

gradlePlugin {
    plugins {
        register("org.example.myplugin") {
            implementationClass = "org.example.MyPlugin"
        }
    }
    testSourceSets(functionalTest.get().sources) // (3)
}

build.gradle

def functionalTest = testing.suites.register("functionalTest", JvmTestSuite) { // (1)
    useJUnitJupiter()
    dependencies {
        implementation("commons-io:commons-io:2.16.1")
        implementation(project())
        implementation(gradleTestKit()) // (2)
    }
}

tasks.check {
    dependsOn(functionalTest)
}

gradlePlugin {
    plugins {
        register("org.example.myplugin") {
            implementationClass = "org.example.MyPlugin"
        }
    }

    testSourceSets functionalTest.get().sources // (3)
}

Define the new test suite: Creates a functionalTest JVM Test Suite.
Add TestKit dependency: This contains the GradleRunner class we’ll use to write tests.
Make the java-gradle-plugin aware of the new test suite: Now the usable plugin source from the project’s main production code will be available to these tests.

With this setup in place, we can write functional tests for our plugin in the build-logic/src/functionalTest/java directory. You can run ./gradlew :build-logic:functionalTest or ./gradlew :build-logic:check from the root project directory to execute these tests.

Note

By default, tests within the included build-logic build are not executed when you run tests in the root project. Because the root project only requires the build artifacts from build-logic, Gradle will build the project without running its internal tests. To run them, you must explicitly invoke the tasks: ./gradlew :build-logic:check.

In the functional test class, we use TestKit to initialize a temporary Gradle project, apply our plugin, and verify that it behaves as expected.

MyPluginFunctionalTest.java

package org.example;

import org.gradle.testkit.runner.BuildResult;
import org.gradle.testkit.runner.GradleRunner;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;

import java.nio.file.Files;
import java.io.File;
import java.io.IOException;

import org.apache.commons.io.FileUtils;

import static org.gradle.testkit.runner.TaskOutcome.FROM_CACHE;
import static org.gradle.testkit.runner.TaskOutcome.SUCCESS;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

public class MyPluginFunctionalTest {
    @TempDir File testProjectDir;
    private File settingsFile;
    private File buildFile;
    private File cacheDir = new File("build-cache");

    @BeforeEach
    public void setup() throws IOException {
        settingsFile = new File(testProjectDir, "settings.gradle");
        Files.writeString(settingsFile.toPath(), "rootProject.name = 'test-project'");

        buildFile = new File(testProjectDir, "build.gradle");
    }

    @Test
    public void testTaskRegistration() throws IOException { // (1)
        String buildFileContent = """
            plugins {
                id("org.example.myplugin")
            }
        """;
        Files.writeString(buildFile.toPath(), buildFileContent);

        BuildResult result = GradleRunner.create()
            .withProjectDir(testProjectDir)
            .withPluginClasspath()
            .forwardOutput()
            .withArguments("tasks", "--all")
            .build();

        assertContainsIgnoringEol("""
            Custom Tasks tasks
            ------------------
            task1
            task2
            """,
            result.getOutput()
        );
    }

    @Test
    public void testTaskExecution() throws IOException { // (2)
        File outputFile = new File(testProjectDir, "build/output.txt");

        String buildFileContent = """
            plugins {
                id("org.example.myplugin")
            }

            myExtension {
                firstName = "John"
                lastName = "Smith"
            }

            tasks.task1 {
                outputFile = project.layout.buildDirectory.file("output.txt")
            }
        """;
        Files.writeString(buildFile.toPath(), buildFileContent);

        GradleRunner.create()
            .withProjectDir(testProjectDir)
            .withPluginClasspath()
            .withArguments("task1")
            .build();

        String actual = Files.readString(outputFile.toPath());
        assertTrue(actual.startsWith("Hi, John Smith, it's currently"));
    }

    @Test
    public void testTaskDeterminism() throws IOException { // (3)
        File outputFile = new File(testProjectDir, "build/output.txt");

        String buildFileContent = """
            plugins {
                id("org.example.myplugin")
            }

            myExtension {
                firstName = "John"
                lastName = "Smith"
            }

            tasks.task1 {
                outputFile = project.layout.buildDirectory.file("output.txt")
                today = ZonedDateTime.parse("2026-01-12T16:00:00-05:00").toInstant()
            }
        """;
        Files.writeString(buildFile.toPath(), buildFileContent);

        GradleRunner runner = GradleRunner.create()
            .withProjectDir(testProjectDir)
            .withPluginClasspath();

        runner.withArguments("task1").build();
        String output1 = Files.readString(outputFile.toPath());

        runner.withArguments("task1", "--rerun-tasks").build();
        String output2 = Files.readString(outputFile.toPath());

        assertEquals(output1, output2);
    }

    @Test
    public void testTaskCacheability() throws IOException { // (4)
        String buildFileContent = """
            plugins {
                id("org.example.myplugin")
            }

            myExtension {
                firstName = "John"
                lastName = "Smith"
            }

            tasks.task1 {
                outputFile = project.layout.buildDirectory.file("output.txt")
                today = ZonedDateTime.parse("2026-01-12T16:00:00-05:00").toInstant()
            }
        """;
        Files.writeString(buildFile.toPath(), buildFileContent);

        GradleRunner runner = GradleRunner.create()
            .withProjectDir(testProjectDir)
            .withPluginClasspath()
            .forwardOutput();

        BuildResult result = runner.withArguments("--build-cache", "task1").build();
        assertEquals(SUCCESS, result.task(":task1").getOutcome());

        FileUtils.deleteDirectory(new File(testProjectDir, "build"));

        result = runner.withArguments("--build-cache", "task1").build();
        assertEquals(FROM_CACHE, result.task(":task1").getOutcome());
    }

    private static void assertContainsIgnoringEol(String expected, String actual) {
        assertTrue(normalizeEol(actual).contains(normalizeEol(expected)));
    }

    private static String normalizeEol(String s) {
        return s.replace("\r\n", "\n").replace("\r", "\n");
    }
}

Looking at the example tests here, you can see various techniques used to verify the plugin’s behavior against actual, ad-hoc Gradle builds defined within the tests:

testTaskRegistration: This test runs the tasks report and verifies the output.
testTaskExecution: This test runs the custom task and verifies its output file.
testTaskDeterminism: This test runs the build twice - forcing tasks to rerun the second time - to ensure the output is identical, which is necessary for caching.
testTaskCacheability: This test checks that when the task is run twice in a row, the second run is loaded from cache.

These examples only scratch the surface of what you can achieve with TestKit. For instance, a comprehensive test for cacheability should verify that changes to inputs correctly trigger re-execution and include tests for relocatability.

You can find more information in the Gradle TestKit documentation.

References

Tags

#plugins, #testing

RUNTIME AND CONFIGURATION

Command-Line Interface

The command-line interface is the primary method of interacting with Gradle.

The following is a reference for executing and customizing the Gradle command-line. It also serves as a reference when writing scripts or configuring continuous integration.

Use of the Gradle Wrapper is highly encouraged. Substitute ./gradlew (in macOS / Linux) or gradlew.bat (in Windows) for gradle in the following examples.

Executing Gradle on the command-line conforms to the following structure:

gradle [taskName...] [--option-name...]

Options are allowed before and after task names.

gradle [--option-name...] [taskName...]

If multiple tasks are specified, you should separate them with a space.

gradle [taskName1 taskName2...] [--option-name...]

Options that accept values can be specified with or without = between the option and argument. The use of = is recommended.

gradle [...] --console=plain

Options that enable behavior have long-form options with inverses specified with --no-. The following are opposites.

gradle [...] --build-cache
gradle [...] --no-build-cache

Many long-form options have short-option equivalents. The following are equivalent:

gradle --help
gradle -h

Note	Many command-line flags can be specified in `gradle.properties` to avoid needing to be typed. See the Configuring build environment guide for details.

Command-line usage

The following sections describe the use of the Gradle command-line interface.

Some plugins also add their own command line options. For example, --tests, which is added by Java test filtering. For more information on exposing command line options for your own tasks, see Declaring command-line options.

Executing tasks

You can learn about what projects and tasks are available in the project reporting section.

Most builds support a common set of tasks known as lifecycle tasks. These include the build, assemble, and check tasks.

To execute a task called myTask on the root project, type:

$ gradle :myTask

This will run the single myTask and all of its dependencies.

Specify options for tasks

To pass an option to a task, prefix the option name with -- after the task name:

$ gradle :exampleTask --exampleOption=exampleValue

Disambiguate task options from built-in options

Gradle does not prevent tasks from registering options that conflict with Gradle’s built-in options, like --profile or --help.

You can fix conflicting task options from Gradle’s built-in options with a -- delimiter before the task name in the command:

$ gradle [--built-in-option-name...] -- [taskName...] [--task-option-name...]

Consider a task named mytask that accepts an option named profile:

In gradle mytask --profile, Gradle accepts --profile as the built-in Gradle option.
In gradle -- mytask --profile=value, Gradle passes --profile as a task option.

Executing tasks in multi-project builds

In a multi-project build, subproject tasks can be executed with : separating the subproject name and task name. The following are equivalent when run from the root project:

$ gradle :subproject:taskName

$ gradle subproject:taskName

You can also run a task for all subprojects using a task selector that consists of only the task name.

The following command runs the test task for all subprojects when invoked from the root project directory:

$ gradle test

To recap:

// Run a task in the root project only
$ gradle :exampleTask --exampleOption=exampleValue

// Run a task that may exist in the root or any subproject (ambiguous if defined in more than one)
$ gradle exampleTask --exampleOption=exampleValue

// Run a task in a specific subproject
$ gradle subproject:exampleTask --exampleOption=exampleValue
$ gradle :subproject:exampleTask --exampleOption=exampleValue

Note	Some tasks selectors, like `help` or `dependencies`, will only run the task on the project they are invoked on and not on all the subprojects.

When invoking Gradle from within a subproject, the project name should be omitted:

$ cd subproject

$ gradle taskName

Tip	When executing the Gradle Wrapper from a subproject directory, reference `gradlew` relatively. For example: `../gradlew taskName`.

Executing multiple tasks

You can also specify multiple tasks. The tasks' dependencies determine the precise order of execution, and a task having no dependencies may execute earlier than it is listed on the command-line.

For example, the following will execute the test and deploy tasks in the order that they are listed on the command-line and will also execute the dependencies for each task.

$ gradle test deploy

Command line order safety

Although Gradle will always attempt to execute the build quickly, command line ordering safety will also be honored.

For example, the following will execute clean and build along with their dependencies:

$ ./gradlew clean build

However, the intention implied in the command line order is that clean should run first and then build. It would be incorrect to execute clean after build, even if doing so would cause the build to execute faster since clean would remove what build created.

Conversely, if the command line order was build followed by clean, it would not be correct to execute clean before build. Although Gradle will execute the build as quickly as possible, it will also respect the safety of the order of tasks specified on the command line and ensure that clean runs before build when specified in that order.

Note that command line order safety relies on tasks properly declaring what they create, consume, or remove.

Excluding tasks from execution

You can exclude a task from being executed using the -x or --exclude-task command-line option and providing the name of the task to exclude:

$ gradle dist --exclude-task test

> Task :compile
compiling source

> Task :dist
building the distribution

BUILD SUCCESSFUL in 0s
2 actionable tasks: 2 executed

You can see that the test task is not executed, even though the dist task depends on it. The test task’s dependencies, such as compileTest, are not executed either. The dependencies of test that other tasks depend on, such as compile, are still executed.

Forcing tasks to execute

You can force Gradle to execute all tasks ignoring up-to-date checks using the --rerun-tasks option:

$ ./gradlew test --rerun-tasks

This will force test and all task dependencies of test to execute. It is similar to running gradle clean test, but without the build’s generated output being deleted.

Alternatively, you can tell Gradle to rerun a specific task using the --rerun built-in task option.

Continue the build after a task failure

By default, Gradle aborts execution and fails the build when any task fails. This allows the build to complete sooner and prevents cascading failures from obfuscating the root cause of an error.

You can use the --continue option to force Gradle to execute every task when a failure occurs:

$ ./gradlew test --continue

When executed with --continue, Gradle executes every task in the build if all the dependencies for that task are completed without failure.

For example, tests do not run if there is a compilation error in the code under test because the test task depends on the compilation task. Gradle outputs each of the encountered failures at the end of the build.

Note	If any tests fail, many test suites fail the entire `test` task. Code coverage and reporting tools frequently run after the test task, so "fail fast" behavior may halt execution before those tools run.

Name abbreviation

When you specify tasks on the command-line, you don’t have to provide the full name of the task. You can provide enough of the task name to identify the task uniquely. For example, it is likely gradle che is enough for Gradle to identify the check task.

The same applies to project names. You can execute the check task in the library subproject with the gradle lib:che command.

You can use camel case patterns for more complex abbreviations. These patterns are expanded to match camel case and kebab case names. For example, the pattern foBa (or fB) matches fooBar and foo-bar.

More concretely, you can run the compileTest task in the my-awesome-library subproject with the command gradle mAL:cT.

$ ./gradlew mAL:cT

> Task :my-awesome-library:compileTest
compiling unit tests

BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed

Abbreviations can also be used with the -x command-line option.

Tracing name expansion

For complex projects, it might be ambiguous if the intended tasks were executed. When using abbreviated names, a single typo can lead to the execution of unexpected tasks.

When INFO, or more verbose logging is enabled, the output will contain extra information about the project and task name expansion.

For example, when executing the mAL:cT command on the previous example, the following log messages will be visible:

No exact project with name ':mAL' has been found. Checking for abbreviated names.
Found exactly one project that matches the abbreviated name ':mAL': ':my-awesome-library'.
No exact task with name ':cT' has been found. Checking for abbreviated names.
Found exactly one task name, that matches the abbreviated name ':cT': ':compileTest'.

Common tasks

The following are task conventions applied by built-in and most major Gradle plugins.

Computing all outputs

It is common in Gradle builds for the build task to designate assembling all outputs and running all checks:

$ ./gradlew build

Running applications

It is common for applications to run with the run task, which assembles the application and executes some script or binary:

$ ./gradlew run

Running all checks

It is common for all verification tasks, including tests and linting, to be executed using the check task:

$ ./gradlew check

Cleaning outputs

You can delete the contents of the build directory using the clean task. Doing so will cause pre-computed outputs to be lost, causing significant additional build time for the subsequent task execution:

$ ./gradlew clean

Project reporting

Gradle provides several built-in tasks which show particular details of your build. This can be useful for understanding your build’s structure and dependencies, as well as debugging problems.

Listing projects

Running the projects task gives you a list of the subprojects of the selected project, displayed in a hierarchy:

$ ./gradlew projects

You also get a project report with Build Scan.

Listing tasks

Running gradle tasks gives you a list of the main tasks of the selected project. This report shows the default tasks for the project, if any, and a description for each task:

$ ./gradlew tasks

By default, this report shows only those tasks assigned to a task group.

Groups (such as verification, publishing, help, build…) are available as the header of each section when listing tasks:

> Task :tasks

Build tasks
-----------
assemble - Assembles the outputs of this project.

Build Setup tasks
-----------------
init - Initializes a new Gradle build.

Distribution tasks
------------------
assembleDist - Assembles the main distributions

Documentation tasks
-------------------
javadoc - Generates Javadoc API documentation for the main source code.

You can obtain more information in the task listing using the --all option:

$ ./gradlew tasks --all

The option --no-all can limit the report to tasks assigned to a task group.

If you need to be more precise, you can display only the tasks from a specific group using the --group option:

$ ./gradlew tasks --group="build setup"

You can use the --provenance option to show where each task was registered (e.g., by a plugin or build script):

$ ./gradlew tasks --provenance

Build tasks
-----------
assemble - Assembles the outputs of this project. (registered by plugin 'org.gradle.language.base.plugins.LifecycleBasePlugin')
build - Assembles and tests this project. (registered by plugin 'org.gradle.language.base.plugins.LifecycleBasePlugin')

Show task usage details

Running gradle help --task someTask gives you detailed information about a specific task:

$ ./gradlew -q help --task libs

Detailed task information for libs

Paths
     :api:libs (registered in build file 'api/build.gradle')
     :webapp:libs (registered in build file 'webapp/build.gradle')

Type
     Task (org.gradle.api.Task)

Options
     --rerun     Causes the task to be re-run even if up-to-date.

Description
     Builds the JAR

Group
     build

This information includes the full task path, the task type, possible task-specific command line options, and the description of the given task. The output also includes provenance information showing where the task was registered (e.g., in a build file or by a plugin).

You can get detailed information about the task class types using the --types option or using --no-types to hide this information.

Reporting dependencies

Build Scan gives a full, visual report of what dependencies exist on which configurations, transitive dependencies, and dependency version selection. They can be invoked using the --scan options:

$ ./gradlew myTask --scan

This will give you a link to a web-based report, where you can find dependency information like this:

Listing project dependencies

Running the dependencies task gives you a list of the dependencies of the selected project, broken down by configuration. For each configuration, the direct and transitive dependencies of that configuration are shown in a tree.

Below is an example of this report:

$ ./gradlew dependencies

> Task :app:dependencies

------------------------------------------------------------
Project ':app'
------------------------------------------------------------

compileClasspath - Compile classpath for source set 'main'.
+--- project :model
|    \--- org.json:json:20220924
+--- com.google.inject:guice:5.1.0
|    +--- javax.inject:javax.inject:1
|    +--- aopalliance:aopalliance:1.0
|    \--- com.google.guava:guava:30.1-jre -> 28.2-jre
|         +--- com.google.guava:failureaccess:1.0.1
|         +--- com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava
|         +--- com.google.code.findbugs:jsr305:3.0.2
|         +--- org.checkerframework:checker-qual:2.10.0 -> 3.28.0
|         +--- com.google.errorprone:error_prone_annotations:2.3.4
|         \--- com.google.j2objc:j2objc-annotations:1.3
+--- com.google.inject:guice:{strictly 5.1.0} -> 5.1.0 (c)
+--- org.json:json:{strictly 20220924} -> 20220924 (c)
+--- javax.inject:javax.inject:{strictly 1} -> 1 (c)
+--- aopalliance:aopalliance:{strictly 1.0} -> 1.0 (c)
+--- com.google.guava:guava:{strictly [28.0-jre, 28.5-jre]} -> 28.2-jre (c)
+--- com.google.guava:guava:{strictly 28.2-jre} -> 28.2-jre (c)
+--- com.google.guava:failureaccess:{strictly 1.0.1} -> 1.0.1 (c)
+--- com.google.guava:listenablefuture:{strictly 9999.0-empty-to-avoid-conflict-with-guava} -> 9999.0-empty-to-avoid-conflict-with-guava (c)
+--- com.google.code.findbugs:jsr305:{strictly 3.0.2} -> 3.0.2 (c)
+--- org.checkerframework:checker-qual:{strictly 3.28.0} -> 3.28.0 (c)
+--- com.google.errorprone:error_prone_annotations:{strictly 2.3.4} -> 2.3.4 (c)
\--- com.google.j2objc:j2objc-annotations:{strictly 1.3} -> 1.3 (c)

Concrete examples of build scripts and output available in Viewing and debugging dependencies.

Running the buildEnvironment task visualises the buildscript dependencies of the selected project, similarly to how gradle dependencies visualizes the dependencies of the software being built:

$ ./gradlew buildEnvironment

Running the dependencyInsight task gives you an insight into a particular dependency (or dependencies) that match specified input:

$ ./gradlew dependencyInsight --dependency [...] --configuration [...]

The --configuration parameter restricts the report to a particular configuration such as compileClasspath.

Listing project properties

Running the properties task gives you a list of the properties of the selected project:

$ ./gradlew -q api:properties

------------------------------------------------------------
Project ':api'
------------------------------------------------------------

allprojects: [project ':api']
ant: org.gradle.api.internal.project.DefaultAntBuilder@12345
antBuilderFactory: org.gradle.api.internal.project.DefaultAntBuilderFactory@12345
artifacts: org.gradle.api.internal.artifacts.dsl.DefaultArtifactHandler_Decorated@12345
asDynamicObject: DynamicObject for project ':api'
baseClassLoaderScope: org.gradle.api.internal.initialization.DefaultClassLoaderScope@12345

You can also query a single property with the optional --property argument:

$ ./gradlew -q api:properties --property allprojects

------------------------------------------------------------
Project ':api'
------------------------------------------------------------

allprojects: [project ':api']

Command-line completion

Gradle provides bash and zsh tab completion support for tasks, options, and Gradle properties through gradle-completion (installed separately):

Debugging options

-?, -h, --help: Shows a help message with the built-in CLI options organized into logical sections. To show project-contextual options, including help on a specific task, see the help task.
-v, --version: Prints Gradle, Groovy, Ant, Launcher & Daemon JVM, and operating system version information and exit without executing any tasks.
-V, --show-version: Prints Gradle, Groovy, Ant, Launcher & Daemon JVM, and operating system version information and continue execution of specified tasks.
-S, --full-stacktrace: Print out the full (very verbose) stacktrace for any exceptions. See also logging options.
-s, --stacktrace: Print out the stacktrace also for user exceptions (e.g. compile error). See also logging options.
--scan: Create a Build Scan with fine-grained information about all aspects of your Gradle build.
-Dorg.gradle.debug=true: A Gradle property that debugs the Gradle Daemon process. Gradle will wait for you to attach a debugger at localhost:5005 by default.
-Dorg.gradle.debug.host=(host address): A Gradle property that specifies the host address to listen on or connect to when debug is enabled. In the server mode on Java 9 and above, passing * for the host will make the server listen on all network interfaces. By default, no host address is passed to JDWP, so on Java 9 and above, the loopback address is used, while earlier versions listen on all interfaces.
-Dorg.gradle.debug.port=(port number): A Gradle property that specifies the port number to listen on when debug is enabled. Default is 5005.
-Dorg.gradle.debug.server=(true,false): A Gradle property that if set to true and debugging is enabled, will cause Gradle to run the build with the socket-attach mode of the debugger. Otherwise, the socket-listen mode is used. Default is true.
-Dorg.gradle.debug.suspend=(true,false): A Gradle property that if set to true and debugging is enabled, the JVM running Gradle will suspend until a debugger is attached. Default is true.

Performance options

Try these options when optimizing and improving build performance.

Many of these options can be specified in the gradle.properties file, so command-line flags are unnecessary.

--build-cache, --no-build-cache: Toggles the Gradle Build Cache. Gradle will try to reuse outputs from previous builds. Default is off.
--configuration-cache, --no-configuration-cache: Toggles the Configuration Cache. Gradle will try to reuse the build configuration from previous builds. Default is off.
--configuration-cache-problems=(fail,warn): Configures how the configuration cache handles problems. Default is fail.

Set to warn to report problems without failing the build.

Set to fail to report problems and fail the build if there are any problems.
--configure-on-demand, --no-configure-on-demand Incubating: Toggles configure-on-demand. Only relevant projects are configured in this build run. Default is off.
--isolated-projects, --no-isolated-projects Incubating: Toggles Isolated Projects. Projects are configured in parallel. Implies --configuration-cache. Default is off.
--max-workers: Sets the maximum number of workers that Gradle may use. Default is number of processors.
--parallel, --no-parallel: Build projects in parallel. For limitations of this option, see Parallel Project Execution. Default is off.
--priority: Specifies the scheduling priority for the Gradle daemon and all processes launched by it. Values are normal or low. Default is normal.
--profile: Generates a high-level performance report in the layout.buildDirectory.dir("reports/profile") directory. --scan is preferred.
--scan: Generate a Build Scan with detailed performance diagnostics.

--watch-fs, --no-watch-fs: Toggles watching the file system. When enabled, Gradle reuses information it collects about the file system between builds. Enabled by default on operating systems where Gradle supports this feature.

Gradle daemon options

You can manage the Gradle Daemon through the following command line options.

--daemon, --no-daemon: Use the Gradle Daemon to run the build. Starts the daemon if not running or the existing daemon is busy. Default is on.
--foreground: Starts the Gradle Daemon in a foreground process.
--status (Standalone command): Run gradle --status to list running and recently stopped Gradle daemons. It only displays daemons of the same Gradle version.
--stop (Standalone command): Run gradle --stop to stop all Gradle Daemons of the same version.
-Dorg.gradle.daemon.idletimeout=(number of milliseconds): A Gradle property wherein the Gradle Daemon will stop itself after this number of milliseconds of idle time. Default is 10800000 (3 hours).

Logging options

Setting log level

You can customize the verbosity of Gradle logging with the following options, ordered from least verbose to most verbose.

-Dorg.gradle.logging.level=(quiet,warn,lifecycle,info,debug): A Gradle property that sets the logging level.
-q, --quiet: Log errors only.
-w, --warn: Set log level to warn.
-i, --info: Set log level to info.
-d, --debug: Log in debug mode (includes normal stacktrace).

Lifecycle is the default log level.

Customizing log format

You can control the use of rich output (colors and font variants) by specifying the console mode in the following ways:

-Dorg.gradle.console=(auto,plain,colored,rich,verbose)

A Gradle property that specifies the console mode. Different modes are described immediately below.

--console=(auto,plain,colored,rich,verbose)

Specifies which type of console output to generate.

Set to plain to generate plain text only. This option disables all color and other rich output in the console output. This is the default when Gradle is not attached to a terminal.

Set to colored to generate colored output without rich status information such as progress bars.

Set to auto (the default) to enable color and other rich output in the console output when the build process is attached to a console or to generate plain text only when not attached to a console. This is the default when Gradle is attached to a terminal.

Set to rich to enable color and other rich output in the console output, regardless of whether the build process is not attached to a console. When not attached to a console, the build output will use ANSI control characters to generate the rich output.

Set to verbose to enable color and other rich output like rich with output task names and outcomes at the lifecycle log level, (as is done by default in Gradle 3.5 and earlier).

Note	When the `NO_COLOR` environment variable is set and non-empty, Gradle suppresses color output regardless of the console mode. Bold, underline, and rich features like progress bars are unaffected. See no-color.org.

Reporting problems

--problems-report (enabled by default) Incubating: Enable the generation of build/reports/problems-report.html. This is the default behaviour. The report is generated with problems provided to the Problems API.
--no-problems-report Incubating: Disable the generation of build/reports/problems-report.html, by default this report is generated with problems provided to the Problems API.

Showing or hiding warnings

By default, Gradle won’t display all warnings (e.g. deprecation warnings). Instead, Gradle will collect them and render a summary at the end of the build like:

Deprecated Gradle features were used in this build, making it incompatible with Gradle 5.0.

You can control the verbosity of warnings on the console with the following options:

-Dorg.gradle.warning.mode=(all,fail,none,summary): A Gradle property that specifies the warning mode. Different modes are described immediately below.
--warning-mode=(all,fail,none,summary): Specifies how to log warnings. Default is summary.

Set to all to log all warnings.

Set to fail to log all warnings and fail the build if there are any warnings.

Set to summary to suppress all warnings and log a summary at the end of the build.

Set to none to suppress all warnings, including the summary at the end of the build.

In all and fail modes, Gradle infers a source location for every problem rather than only the first ones. Past the stack-capture cap (50 problems by default, 5000 under Isolated Projects), the trace is reduced to the originating build logic and the calling script (enough to locate the problem) rather than the full call chain.

Rich console

Gradle’s rich console displays extra information while builds are running.

Features:

Progress bar and timer visually describe the overall status
Parallel work-in-progress lines below describe what is happening now
Colors and fonts are used to highlight significant output and errors

Execution options

The following options affect how builds are executed by changing what is built or how dependencies are resolved.

--include-build: Run the build as a composite, including the specified build.
--offline: Specifies that the build should operate without accessing network resources.
-U, --refresh-dependencies: Refresh the state of dependencies.
--continue: Continue task execution after a task failure.
-m, --dry-run: Run Gradle with all task actions disabled. Use this to show which task would have executed.
--task-graph Since 9.1.0: Run Gradle with all task actions disabled and print the task dependency graph.
-t, --continuous: Enables continuous build. Gradle does not exit and will re-execute tasks when task file inputs change.
--write-locks: Indicates that all resolved configurations that are lockable should have their lock state persisted.
--update-locks <group:name>[,<group:name>]*: Indicates that versions for the specified modules have to be updated in the lock file.

This flag also implies --write-locks.
-a, --no-rebuild: Do not rebuild project dependencies. Useful for debugging and fine-tuning buildSrc, but can lead to wrong results. Use with caution!

Dependency verification options

Learn more about this in dependency verification.

-F=(strict,lenient,off), --dependency-verification=(strict,lenient,off): Configures the dependency verification mode.

The default mode is strict.
-M, --write-verification-metadata: Generates checksums for dependencies used in the project (comma-separated list) for dependency verification.
--refresh-keys: Refresh the public keys used for dependency verification.
--export-keys: Exports the public keys used for dependency verification.

Environment options

You can customize many aspects of build scripts, settings, caches, and so on through the options below.

-g, --gradle-user-home: Specifies the Gradle User Home directory. The default is the .gradle directory in the user’s home directory.
-p, --project-dir: Specifies the start directory for Gradle. Defaults to current directory.
--project-cache-dir: Specifies the project-specific cache directory. Default value is .gradle in the root project directory.
-D, --system-prop: Sets a system property of the JVM, for example -Dmyprop=myvalue.
-I, --init-script: Specifies an initialization script.
-P, --project-prop: Sets a project property of the root project, for example -Pmyprop=myvalue.
-Dorg.gradle.jvmargs: A Gradle property that sets JVM arguments.
-Dorg.gradle.java.home: A Gradle property that sets the JDK home dir.

Non-interactive mode

By default, Gradle may prompt the user for input on the console when an interactive terminal is available. You can disable all interactive prompting by using the --non-interactive command-line option, or by setting the org.gradle.console.interactive Gradle property to false (for example in gradle.properties, GRADLE_OPTS, or via -D).

When interactive prompting is disabled, Gradle uses default values instead of prompting. This is useful for running Gradle in automated environments such as CI pipelines, scripts, and AI agents.

--non-interactive Incubating: Do not prompt for user input.

Task options

Tasks may define task-specific options which are different from most of the global options described in the sections above (which are interpreted by Gradle itself, can appear anywhere in the command line, and can be listed using the --help option).

Task options:

Are consumed and interpreted by the tasks themselves;
Must be specified immediately after the task in the command-line;
May be listed using gradle help --task someTask (see Show task usage details).

To learn how to declare command-line options for your own tasks, see Declaring and Using Command Line Options.

Built-in task options

Built-in task options are options available as task options for all tasks. At this time, the following built-in task options exist:

--rerun: Causes the task to be rerun even if up-to-date. Similar to --rerun-tasks, but for a specific task.

Bootstrapping new projects

Creating new Gradle builds

Use the built-in gradle init task to create a new Gradle build, with new or existing projects.

$ gradle init

Most of the time, a project type is specified. Available types include basic (default), java-library, java-application, and more. See init plugin documentation for details.

$ gradle init --type java-library

Standardize and provision Gradle

The built-in gradle :wrapper task generates a script, gradlew, that invokes a declared version of Gradle, downloading it beforehand if necessary.

$ ./gradlew :wrapper --gradle-version=8.1

You can also specify --distribution-type=(bin|all), --gradle-distribution-url, --gradle-distribution-sha256-sum in addition to --gradle-version.
Full details on using these options are documented in the Gradle wrapper section.

Continuous build

Continuous Build allows you to automatically re-execute the requested tasks when file inputs change. You can execute the build in this mode using the -t or --continuous command-line option.

Learn more in Continuous Builds.

Logging and Output

The build log is the primary way Gradle communicates what’s happening during a build. Clear logging helps you quickly understand your build status, identify issues, and troubleshoot effectively. Too much noise in the logs can obscure important warnings or errors.

Gradle provides flexible logging controls, enabling you to adjust verbosity and detail according to your needs.

Gradle Log levels

Gradle defines six primary log levels:

Level Description

ERROR

Error messages

QUIET

Important information messages

WARNING

Warning messages

LIFECYCLE

Progress information messages

INFO

Information messages

DEBUG

Debug messages

The default logging level is LIFECYCLE, providing progress updates without overwhelming detail.

Choosing and setting a log level

You can set the log level either through command-line options or by configuring the gradle.properties file.

CLI Option Property Outputs Log Levels

-q or --quiet

org.gradle.logging.level=quiet

QUIET and higher

-w or --warn

org.gradle.logging.level=warn

WARN and higher

no logging options

LIFECYCLE and higher

-i or --info

org.gradle.logging.level=info

INFO and higher

-d or --debug

org.gradle.logging.level=debug

DEBUG and higher (all log messages)

For example, to set a consistent log level in your project’s gradle.properties file:

org.gradle.logging.level=info

Similarly on the command line:

$ ./gradlew run --info

You can emit log messages directly from build scripts and tasks using Gradle’s built-in logger:

build.gradle.kts

tasks.register("logtask") {
    doLast {
        logger.lifecycle("Lifecycle: Build progress info.")
        logger.info("Info: Additional insights.")
        logger.debug("Debug: Detailed troubleshooting info.")
    }
}

build.gradle

tasks.register('logtask') {
    doLast {
        logger.lifecycle('Lifecycle: Build progress info.')
        logger.info('Info: Additional insights.')
        logger.debug('Debug: Detailed troubleshooting info.')
    }
}

Use appropriate log levels (lifecycle, info, debug) to ensure your build output is clear and informative.

Caution

The DEBUG log level can expose sensitive security information to the console.

Stacktrace options

Stacktraces are useful for diagnosing issues during a build failure. You can control stacktrace output via command-line options or properties:

CLI Option Gradle Property Stacktrace Shown

--stacktrace or -s

org.gradle.logging.stacktrace=all

Truncated stacktraces are printed. We recommend this over full stacktraces. Groovy full stacktraces are extremely verbose due to the underlying dynamic invocation mechanisms. Yet they usually do not contain relevant information about what has gone wrong in your code. This option renders stacktraces for deprecation warnings.

--full-stacktrace or -S

org.gradle.logging.stacktrace=full

The full stacktraces are printed out. This option renders stacktraces for deprecation warnings.

(none)

No stacktraces are printed to the console in case of a build error (e.g., a compile error). Only in case of internal exceptions will stacktraces be printed. If the DEBUG log level is chosen, truncated stacktraces are always printed.

For example, to always display a full stacktrace on build errors, set in gradle.properties:

org.gradle.logging.stacktrace=full

Logging Sensitive Information

Running Gradle with the DEBUG log level can potentially expose sensitive information to the console and build log.

This information might include:

Environment variables
Private repository credentials
Build cache and Develocity credentials
Plugin Portal publishing credentials

It’s important to avoid using the DEBUG log level when running on public Continuous Integration (CI) services. Build logs on these services are accessible to the public and can expose sensitive information. Even on private CI services, logging sensitive credentials may pose a risk depending on your organization’s threat model. It’s advisable to discuss this with your organization’s security team.

Some CI providers attempt to redact sensitive credentials from logs, but this process is not foolproof and typically only redacts exact matches of pre-configured secrets.

If you suspect that a Gradle Plugin may inadvertently expose sensitive information, please contact our security team for assistance with disclosure.

Custom log messages

A simple option for logging in your build file is to write messages to standard output. Gradle redirects anything written to standard output to its logging system at the QUIET log level:

build.gradle.kts

println("A message which is logged at QUIET level")

build.gradle

println 'A message which is logged at QUIET level'

Gradle also provides a logger property to a build script, which is an instance of Logger. This interface extends the SLF4J Logger interface and adds a few Gradle-specific methods. Below is an example of how this is used in the build script:

build.gradle.kts

logger.quiet("An info log message which is always logged.")
logger.error("An error log message.")
logger.warn("A warning log message.")
logger.lifecycle("A lifecycle info log message.")
logger.info("An info log message.")
logger.debug("A debug log message.")
logger.trace("A trace log message.") // Gradle never logs TRACE level logs

build.gradle

logger.quiet('An info log message which is always logged.')
logger.error('An error log message.')
logger.warn('A warning log message.')
logger.lifecycle('A lifecycle info log message.')
logger.info('An info log message.')
logger.debug('A debug log message.')
logger.trace('A trace log message.') // Gradle never logs TRACE level logs

Use the link typical SLF4J pattern to replace a placeholder with an actual value in the log message.

build.gradle.kts

logger.info("A {} log message", "info")

build.gradle

logger.info('A {} log message', 'info')

You can also hook into Gradle’s logging system from within other classes used in the build (classes from the buildSrc directory, for example) with an SLF4J logger. You can use this logger the same way as you use the provided logger in the build script.

build.gradle.kts

import org.slf4j.LoggerFactory

val slf4jLogger = LoggerFactory.getLogger("some-logger")
slf4jLogger.info("An info log message logged using SLF4j")

build.gradle

import org.slf4j.LoggerFactory

def slf4jLogger = LoggerFactory.getLogger('some-logger')
slf4jLogger.info('An info log message logged using SLF4j')

Logging from external tools and libraries

Internally, Gradle uses Ant and Ivy. Both have their own logging system. Gradle redirects their logging output into the Gradle logging system.

There is a 1:1 mapping from the Ant/Ivy log levels to the Gradle log levels, except the Ant/Ivy TRACE log level, which is mapped to the Gradle DEBUG log level. This means the default Gradle log level will not show any Ant/Ivy output unless it is an error or a warning.

Many tools out there still use the standard output for logging. By default, Gradle redirects standard output to the QUIET log level and standard error to the ERROR level. This behavior is configurable.

The project object provides a LoggingManager, which allows you to change the log levels that standard out or error are redirected to when your build script is evaluated.

build.gradle.kts

logging.captureStandardOutput(LogLevel.INFO)
println("A message which is logged at INFO level")

build.gradle

logging.captureStandardOutput LogLevel.INFO
println 'A message which is logged at INFO level'

To change the log level for standard out or error during task execution, use a LoggingManager.

build.gradle.kts

tasks.register("logInfo") {
    logging.captureStandardOutput(LogLevel.INFO)
    doFirst {
        println("A task message which is logged at INFO level")
    }
}

build.gradle

tasks.register('logInfo') {
    logging.captureStandardOutput LogLevel.INFO
    doFirst {
        println 'A task message which is logged at INFO level'
    }
}

Gradle also integrates with the Java Util Logging, Jakarta Commons Logging and Log4j logging toolkits. Any log messages your build classes write using these logging toolkits will be redirected to Gradle’s logging system.

Changing what Gradle logs

Warning

This feature is deprecated and will be removed in the next major version without a replacement.

The configuration cache limits the ability to customize Gradle’s logging UI. The custom logger can only implement supported listener interfaces. These interfaces do not receive events when the configuration cache entry is reused because the configuration phase is skipped.

You can replace much of Gradle’s logging UI with your own. You could do this if you want to customize the UI somehow - to log more or less information or to change the formatting. Simply replace the logging using the Gradle.useLogger(java.lang.Object) method. This is accessible from a build script, an init script, or via the embedding API. Note that this completely disables Gradle’s default output. Below is an example init script that changes how task execution and build completion are logged:

customLogger.init.gradle.kts

useLogger(CustomEventLogger())

@Suppress("deprecation")
class CustomEventLogger() : BuildAdapter(), TaskExecutionListener {

    override fun beforeExecute(task: Task) {
        println("[${task.name}]")
    }

    override fun afterExecute(task: Task, state: TaskState) {
        println()
    }

    override fun buildFinished(result: BuildResult) {
        println("build completed")
        if (result.failure != null) {
            (result.failure as Throwable).printStackTrace()
        }
    }
}

customLogger.init.gradle

useLogger(new CustomEventLogger())

@SuppressWarnings("deprecation")
class CustomEventLogger extends BuildAdapter implements TaskExecutionListener {

    void beforeExecute(Task task) {
        println "[$task.name]"
    }

    void afterExecute(Task task, TaskState state) {
        println()
    }
    
    void buildFinished(BuildResult result) {
        println 'build completed'
        if (result.failure != null) {
            result.failure.printStackTrace()
        }
    }
}

$ ./gradlew -I customLogger.init.gradle.kts build

> Task :compile
[compile]
compiling source

> Task :testCompile
[testCompile]
compiling test source

> Task :test
[test]
running unit tests

> Task :build
[build]

build completed
3 actionable tasks: 3 executed

$ ./gradlew -I customLogger.init.gradle build

> Task :compile
[compile]
compiling source

> Task :testCompile
[testCompile]
compiling test source

> Task :test
[test]
running unit tests

> Task :build
[build]

build completed
3 actionable tasks: 3 executed

Your logger can implement any of the listener interfaces listed below. When you register a logger, only the logging for the interfaces it implements is replaced. Logging for the other interfaces is left untouched. You can find out more about the listener interfaces in Build lifecycle events.

Gradle Wrapper

The recommended way to execute any Gradle build is with the help of the Gradle Wrapper (referred to as "Wrapper").

The Wrapper is a script (called gradlew or gradlew.bat) that invokes a declared version of Gradle, downloading it beforehand if necessary. Instead of running gradle build using the installed Gradle, you use the Gradle Wrapper by calling ./gradlew build.

The Gradle Wrapper isn’t distributed as a standalone download. It’s created using the gradle :wrapper task.

There are three ways to use the Wrapper:

Adding the Wrapper - You set up a new Gradle project and add the Wrapper to it.
Using the Wrapper - You run a project with the Wrapper that already provides it.
Upgrading the Wrapper - You upgrade the Wrapper to a new version of Gradle.

When using the Wrapper instead of the installed Gradle, you gain the following benefits:

Standardizes a project on a given Gradle version for more reliable and robust builds.
Provisioning the Gradle version for different users is done with a simple Wrapper definition change.
Provisioning the Gradle version for different execution environments (e.g., IDEs or Continuous Integration servers) is done with a simple Wrapper definition change.

The following sections explain each of these use cases in more detail.

1. Adding the Gradle Wrapper

The Gradle Wrapper is not something you download.

Generating the Wrapper (and its files) requires an installed version of Gradle as described in Installation.

Tip	The Build Init Plugin (`gradle init`) automatically generates the Wrapper files when creating a new project.

Every vanilla Gradle build comes with a built-in task called wrapper. The task is listed under the group "Build Setup tasks" when listing the tasks.

Note

When invoking the wrapper task, use gradle :wrapper. The : prefix explicitly targets the root project, which is the only project where the wrapper task is relevant. This matters for Configure on Demand and Isolated Projects, where addressing the root project directly avoids unnecessary project configuration.

Executing the wrapper task generates the necessary Wrapper files in the project directory:

$ gradle :wrapper

> Task :wrapper

BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed

Tip

To make the Wrapper files available to other developers and execution environments, you need to check them into version control.

Wrapper files, including the JAR file, are small. Adding the JAR file to version control is expected. Some organizations do not allow projects to submit binary files to version control, and there is no workaround available.

The generated Wrapper properties file, gradle/wrapper/gradle-wrapper.properties, stores the information about the Gradle distribution:

The server hosting the Gradle distribution.
The type of Gradle distribution. By default, the -bin distribution contains only the runtime but no sample code and documentation.
The Gradle version used for executing the build. By default, the wrapper task picks the same Gradle version used to generate the Wrapper files.
Optionally, a timeout in ms used when downloading the Gradle distribution.
Optionally, a boolean to set the validation of the distribution URL.

The following is an example of the generated distribution URL in gradle/wrapper/gradle-wrapper.properties:

distributionUrl=https\://services.gradle.org/distributions/gradle-9.7.0-bin.zip

Tip	Use the `-bin` distribution for most builds. The `-bin` distribution contains only the runtime needed to build and run Gradle. It’s smaller to download and faster to cache on CI systems compared to the `-all` distribution, which also includes Gradle’s full source code and documentation.

All of those aspects are configurable at the time of generating the Wrapper files with the help of the following command line options:

--gradle-version

The Gradle version used for downloading and executing the Wrapper. The resulting distribution URL is validated before it is written to the properties file.

For Gradle versions starting with major version 9, the version can be specified using only the major or minor version number. In such cases, the latest normal release matching that major or minor version will be used. For example, 9 resolves to the latest 9.x.y release, and 9.1 resolves to the latest 9.1.x release.

The following labels are allowed:

--distribution-type

The Gradle distribution type used for the Wrapper. Available options are bin and all. The default value is bin.

--gradle-distribution-url

The full URL pointing to the Gradle distribution ZIP file. This option makes --gradle-version and --distribution-type obsolete, as the URL already contains this information. This option is valuable if you want to host the Gradle distribution inside your company’s network. The URL is validated before it is written to the properties file.

--gradle-distribution-sha256-sum

The SHA256 hash sum used for verifying the downloaded Gradle distribution.

--network-timeout

The network timeout to use when downloading the Gradle distribution, in ms. The default value is 10000.

--no-validate-url

Disables the validation of the configured distribution URL.

--validate-url

Enables the validation of the configured distribution URL. Enabled by default.

--retries

The number of retries to attempt when downloading the Gradle distribution. The default value is 0, meaning retrying is disabled, downloading will be attempted a single time. Negative values will be ignored and the default will be used.

--retry-back-off-ms

The initial back off in milliseconds to wait between download retries (if enabled, see --retries). The delay doubles after each consecutive failure. The default value is 500 milliseconds, meaning we will wait half a second after the first failed download attempt, 1 second after the second attempt and so on. Negative values will be ignored and the default will be used.

If the distribution URL is configured with --gradle-version or --gradle-distribution-url, the URL is validated by sending a HEAD request in the case of the https scheme or by checking the existence of the file in the case of the file scheme.

Let’s assume the following use case to illustrate combining command line options. You would like to generate the Wrapper with version 9.7.0 and use the -all distribution to include the Gradle source code and documentation alongside the runtime.

The following command-line execution captures those requirements:

$ gradle :wrapper --gradle-version 9.7.0 --distribution-type all

> Task :wrapper

BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed

As a result, you can find the desired information (the generated distribution URL) in the Wrapper properties file:

distributionUrl=https\://services.gradle.org/distributions/gradle-9.7.0-all.zip

Let’s have a look at the following project layout to illustrate the expected Wrapper files:

.
├── a-subproject
│   └── build.gradle.kts
├── settings.gradle.kts
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
└── gradlew.bat

.
├── a-subproject
│   └── build.gradle
├── settings.gradle
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
└── gradlew.bat

A Gradle project typically provides a settings.gradle(.kts) file and one build.gradle(.kts) file for each subproject. The Wrapper files live alongside in the gradle directory and the root directory of the project.

The following list explains their purpose:

gradle-wrapper.jar: The Wrapper JAR file containing code for downloading the Gradle distribution.
gradle-wrapper.properties: A properties file responsible for configuring the Wrapper runtime behavior e.g. the Gradle version compatible with this version. Note that more generic settings, like configuring the Wrapper to use a proxy, need to go into a different file.
gradlew, gradlew.bat: A shell script and a Windows batch script for executing the build with the Wrapper.

You can go ahead and execute the build with the Wrapper without installing the Gradle runtime. If the project you are working on does not contain those Wrapper files, you will need to generate them.

2. Using the Gradle Wrapper

It is always recommended to execute a build with the Wrapper to ensure a reliable, controlled, and standardized execution of the build. Using the Wrapper looks like running the build with a Gradle installation. Depending on the operating system you either run gradlew or gradlew.bat instead of the gradle command.

The following console output demonstrates the use of the Wrapper on a Windows machine for a Java-based project:

$ gradlew.bat build

Downloading https://services.gradle.org/distributions/gradle-5.0-all.zip
.....................................................................................
Unzipping C:\Documents and Settings\Claudia\.gradle\wrapper\dists\gradle-5.0-all\ac27o8rbd0ic8ih41or9l32mv\gradle-5.0-all.zip to C:\Documents and Settings\Claudia\.gradle\wrapper\dists\gradle-5.0-al\ac27o8rbd0ic8ih41or9l32mv
Set executable permissions for: C:\Documents and Settings\Claudia\.gradle\wrapper\dists\gradle-5.0-all\ac27o8rbd0ic8ih41or9l32mv\gradle-5.0\bin\gradle

BUILD SUCCESSFUL in 12s
1 actionable task: 1 executed

If the Gradle distribution was not provisioned to GRADLE_USER_HOME before, the Wrapper will download it and store it in GRADLE_USER_HOME. Any subsequent build invocation will reuse the existing local distribution as long as the distribution URL in the Gradle properties doesn’t change.

Note	The Wrapper shell script and batch file reside in the root directory of a single or multi-project Gradle build. You will need to reference the correct path to those files in case you want to execute the build from a subproject directory e.g. `../../gradlew tasks`.

3. Upgrading the Gradle Wrapper

Projects typically want to keep up with the times and upgrade their Gradle version to benefit from new features and improvements.

The recommended option is to run the wrapper task and provide the target Gradle version as described in Adding the Gradle Wrapper. Using the wrapper task ensures that any optimizations made to the Wrapper shell script or batch file with that specific Gradle version are applied to the project.

As usual, you should commit the changes to the Wrapper files to version control.

Note that running the wrapper task once will update gradle-wrapper.properties only, but leave the Wrapper itself in gradle-wrapper.jar untouched. This is usually fine as new versions of Gradle can be run even with older Wrapper files.

Note	If you want all the Wrapper files to be completely up-to-date, you will need to run the `wrapper` task a second time.

The following command upgrades the Wrapper to the latest version:

$ ./gradlew :wrapper --gradle-version latest   // MacOs, Linux

$ gradlew.bat :wrapper --gradle-version latest // Windows

BUILD SUCCESSFUL in 4s
1 actionable task: 1 executed

The following command upgrades the Wrapper to a specific version:

$ ./gradlew :wrapper --gradle-version 9.7.0 // MacOs, Linux

$ gradlew.bat :wrapper --gradle-version 9.7.0 // Windows

BUILD SUCCESSFUL in 4s
1 actionable task: 1 executed

Once you have upgraded the Wrapper, you can check that it’s the version you expected by executing ./gradlew --version.

Tip	Don’t forget to run the `wrapper` task again to download the Gradle distribution binaries (if needed) and update the `gradlew` and `gradlew.bat` files.

Another way to upgrade the Gradle version is by manually changing the distributionUrl property in the Wrapper’s gradle-wrapper.properties file. The tip above also applies in this case.

Note	Since Gradle 9.0.0, the version always uses the `X.Y.Z` format. Using only the major or minor version is not supported in `gradle-wrapper.properties`.

Customizing the Gradle Wrapper

Most users of Gradle are happy with the default runtime behavior of the Wrapper. However, organizational policies, security constraints or personal preferences might require you to dive deeper into customizing the Wrapper.

Thankfully, the built-in wrapper task exposes numerous options to bend the runtime behavior to your needs. Most configuration options are exposed by the underlying task type Wrapper.

Let’s assume you grew tired of defining the -all distribution type on the command line every time you upgrade the Wrapper. You can save yourself some keyboard strokes by re-configuring the wrapper task.

build.gradle.kts

tasks.wrapper {
    distributionType = Wrapper.DistributionType.ALL
}

build.gradle

tasks.named('wrapper') {
    distributionType = Wrapper.DistributionType.ALL
}

With the configuration in place, running ./gradlew :wrapper --gradle-version 9.7.0 is enough to produce a distributionUrl value in the Wrapper properties file that will request the -all distribution:

distributionUrl=https\://services.gradle.org/distributions/gradle-9.7.0-all.zip

Check out the API documentation for a more detailed description of the available configuration options. You can also find various samples for configuring the Wrapper in the Gradle distribution.

Authenticated Gradle Distribution Download

The Gradle Wrapper can download Gradle distributions from servers using HTTP Basic Authentication or with a static HTTP Bearer Token. This enables you to host the Gradle distribution on a private protected server.

You can specify a username and password in two different ways depending on your use case: as system properties or directly embedded in the distributionUrl. Credentials in system properties take precedence over the ones embedded in distributionUrl.

Tip	Any Authentication (HTTP Basic / Bearer Token) should only be used with `HTTPS` URLs and not plain `HTTP` ones. With Basic Authentication, the user credentials are sent in clear text. With Bearer Token, the Token itself is sent in clear text.

System properties can be specified in the .gradle/gradle.properties file in the user’s home directory or by other means.

To specify the HTTP Basic Authentication credentials, add the following lines to the system properties file:

systemProp.gradle.wrapperUser=username
systemProp.gradle.wrapperPassword=password

Embedding credentials in the distributionUrl in the gradle/wrapper/gradle-wrapper.properties file also works. Please note that this file is to be committed into your source control system.

Tip	Shared credentials embedded in `distributionUrl` should only be used in a controlled environment.

To specify the HTTP Basic Authentication credentials in distributionUrl, add the following line:

distributionUrl=https://username:password@somehost/path/to/gradle-distribution.zip

This can be used in conjunction with a proxy, authenticated or not. See Accessing the web via a proxy for more information on how to configure the Wrapper to use a proxy.

Warning

Using systemProp.gradle.wrapperUser and systemProp.gradle.wrapperPassword may leak your credentials if the build attempts to download the Gradle Wrapper from a server other than your private one.

To safeguard your credentials, prefix these system properties with your private server’s hostname, replacing all dots (.) with underscores (_).

Note	Hostnames are not case-sensitive thus Gradle converts the hostname in the property name into lowercase. That is, if you wrote `EXAMPLE.COM` in your Wrapper configuration, then you have to use the string `example_com` in the system property key.

For example, if your private server hostname is your.example.com, use the following system properties:

systemProp.gradle.your_example_com.wrapperUser=username
systemProp.gradle.your_example_com.wrapperPassword=password

To authenticate with a static HTTP Bearer Token, add the following line to your Gradle properties file:

systemProp.gradle.your_example_com.wrapperToken=some-api-token

Note

If a wrapperToken is specified, it will take precedence over wrapperUser and wrapperPassword system properties (and also over user & password values embedded in the URL). It is strongly recommended to include the hostname in the property to prevent the token from being sent to an unintended server by accident.

Configuring Wrapper Retries

The Gradle Wrapper can be configured to automatically retry downloading the Gradle distribution. This is useful in environments with unstable network connections.

You can configure the number of retries and the back off between attempts in the gradle-wrapper.properties file:

retries=3
retryBackOffMs=1000 # initial delay; doubles on each subsequent failure

Verification of Downloaded Gradle Distributions

The Gradle Wrapper allows for verification of the downloaded Gradle distribution via SHA-256 hash sum comparison. This increases security against targeted attacks by preventing a man-in-the-middle attacker from tampering with the downloaded Gradle distribution.

To enable this feature, download the .sha256 file associated with the Gradle distribution you want to verify.

Downloading the SHA-256 File

You can download the .sha256 file from the stable releases or release candidate and nightly releases. The format of the file is a single line of text that is the SHA-256 hash of the corresponding zip file.

You can also reference the list of Gradle distribution checksums.

Configuring Checksum Verification

Add the downloaded (SHA-256 checksum) hash sum to gradle-wrapper.properties using the distributionSha256Sum property or use --gradle-distribution-sha256-sum on the command-line:

distributionSha256Sum=371cb9fbebbe9880d147f59bab36d61eee122854ef8c9ee1ecf12b82368bcf10

Gradle will report a build failure if the configured checksum does not match the checksum found on the server hosting the distribution. Checksum verification is only performed if the configured Wrapper distribution hasn’t been downloaded yet.

Note	The `wrapper` task fails if `gradle-wrapper.properties` contains `distributionSha256Sum`, but the task configuration does not define a sum. Executing the `wrapper` task preserves the `distributionSha256Sum` configuration when the Gradle version does not change.

Verifying the Integrity of the Gradle Wrapper JAR

The Wrapper JAR is a binary file that will be executed on the computers of developers and build servers. As with all such files, you should ensure it’s trustworthy before executing it.

Since the Wrapper JAR is usually checked into a project’s version control system, there is the potential for a malicious actor to replace the original JAR with a modified one by submitting a pull request that only upgrades the Gradle version.

The Setup Gradle GitHub Action automatically validates the Wrapper JAR as part of every build. As of v4, Wrapper validation is built in, no separate action is needed.

Gradle also publishes the checksums of all releases (except for version 3.3 to 4.0.2, which did not generate reproducible JARs), so you can manually verify the integrity of the Wrapper JAR.

Automatically Verifying the Gradle Wrapper JAR on GitHub

The Setup Gradle GitHub Action validates the Wrapper JAR automatically. See the Wrapper validation documentation for configuration options.

Manually Verifying the Gradle Wrapper JAR

You can manually verify the checksum of the Wrapper JAR to ensure that it has not been tampered with by running the following commands on one of the major operating systems.

Manually verifying the checksum of the Wrapper JAR on Linux:

$ cd gradle/wrapper

$ curl --location --output gradle-wrapper.jar.sha256 \
       https://services.gradle.org/distributions/gradle-9.7.0-wrapper.jar.sha256

$ echo " gradle-wrapper.jar" >> gradle-wrapper.jar.sha256

$ sha256sum --check gradle-wrapper.jar.sha256

gradle-wrapper.jar: OK

Manually verifying the checksum of the Wrapper JAR on macOS:

$ cd gradle/wrapper

$ curl --location --output gradle-wrapper.jar.sha256 \
       https://services.gradle.org/distributions/gradle-9.7.0-wrapper.jar.sha256

$ echo " gradle-wrapper.jar" >> gradle-wrapper.jar.sha256

$ sha256sum --check gradle-wrapper.jar.sha256

gradle-wrapper.jar: OK

Manually verifying the checksum of the Wrapper JAR on Windows (using PowerShell):

> $expected = Invoke-RestMethod -Uri https://services.gradle.org/distributions/gradle-9.7.0-wrapper.jar.sha256

> $actual = (Get-FileHash gradle\wrapper\gradle-wrapper.jar -Algorithm SHA256).Hash.ToLower()

> @{$true = 'OK: Checksum match'; $false = "ERROR: Checksum mismatch!`nExpected: $expected`nActual:   $actual"}[$actual -eq $expected]

OK: Checksum match

Verifying the Gradle Wrapper JAR with PGP

In addition to checksum verification, you can verify the Wrapper JAR using its PGP signature. Gradle publishes PGP signatures for all distribution artifacts, including the Wrapper JAR.

First, import the Gradle public key (see Gradle Keys for details):

$ curl --location https://keys.openpgp.org/vks/v1/by-fingerprint/7B79310A0A3F8B081C8A0B4EE0A56BE8F025F892 | gpg --import

Then download the signature file and verify:

$ cd gradle/wrapper
$ curl --location --output gradle-wrapper.jar.asc \
       https://services.gradle.org/distributions/gradle-9.7.0-wrapper.jar.asc
$ gpg --verify gradle-wrapper.jar.asc gradle-wrapper.jar

A successful verification shows Good signature from "Gradle Inc. <info@gradle.com>".

Troubleshooting a Checksum Mismatch

If the checksum does not match the one you expected, chances are the wrapper task wasn’t executed with the upgraded Gradle distribution.

You should first check whether the actual checksum matches a different Gradle version.

Here are the commands you can run on the major operating systems to generate the actual checksum of the Wrapper JAR.

Generating the checksum of the Wrapper JAR on Linux:

$ sha256sum gradle/wrapper/gradle-wrapper.jar
d81e0f23ade952b35e55333dd5f1821585e887c6d24305aeea2fbc8dad564b95 gradle/wrapper/gradle-wrapper.jar

Generating the actual checksum of the Wrapper JAR on macOS:

$ sha256sum gradle/wrapper/gradle-wrapper.jar
d81e0f23ade952b35e55333dd5f1821585e887c6d24305aeea2fbc8dad564b95 gradle/wrapper/gradle-wrapper.jar

Generating the actual checksum of the Wrapper JAR on Windows (using PowerShell):

> (Get-FileHash gradle\wrapper\gradle-wrapper.jar -Algorithm SHA256).Hash.ToLower()
d81e0f23ade952b35e55333dd5f1821585e887c6d24305aeea2fbc8dad564b95

Once you know the actual checksum, check whether it’s listed on https://gradle.org/release-checksums/. If it is listed, you have verified the integrity of the Wrapper JAR. If the version of Gradle that generated the Wrapper JAR doesn’t match the version in gradle/wrapper/gradle-wrapper.properties, it’s safe to run the :wrapper task again to update the Wrapper JAR.

If the checksum is not listed on the page, the Wrapper JAR might be from a milestone, release candidate, or nightly build or may have been generated by Gradle 3.3 to 4.0.2. Try to find out how it was generated but treat it as untrustworthy until proven otherwise. If you think the Wrapper JAR was compromised, please let the Gradle team know by sending an email to security@gradle.com.

Gradle Daemon

The Gradle Daemon is a long-lived, persistent process that runs in the background and hosts Gradle’s execution engine. It dramatically reduces build times using caching, runtime optimizations, and eliminating JVM startup overhead.

The Gradle Client vs. the Gradle Daemon

To run any Gradle command, your system starts two separate Java Virtual Machine (JVM) processes, which can use different Java versions.

Understanding their distinct roles and how their respective JVM versions are determined is key to effective build configuration and debugging:

Process Role JVM Version Source

Gradle Client JVM

Process that starts when you run gradle or ./gradlew and stays alive for the entire build invocation.
It connects to (or starts) a Daemon, sends the build request, and streams output back to the console.

Uses the JVM that launches the wrapper script (e.g. JAVA_HOME, java on PATH, or your IDE).

Gradle Daemon JVM

Long-lived process that executes the build and caches state between runs.

Uses the JVM set by:
- org.gradle.java.home (properties)
- Tooling API requests (e.g., IDE)
- Daemon JVM toolchains
By default, the Gradle Client will look for compatible daemons* or start a new one if none are available.

*Gradle reuses an existing daemon only if its Java home/version and JVM args (e.g., org.gradle.jvmargs, GRADLE_OPTS) are identical. Changing JVM args (like increasing memory) will spawn a new daemon. In the rare case where the daemon has been disabled (--no-daemon or -Dorg.gradle.daemon=false) and the Client process is compatible, the Gradle Daemon uses the JVM that launched the Gradle Client.

Understanding the Daemon

A daemon is a computer program that runs as a background process rather than being under the direct control of an interactive user.

Gradle runs on the Java Virtual Machine (JVM) and uses several supporting libraries with non-trivial initialization time. Startups can be slow. The Gradle Daemon solves this problem.

The Gradle Daemon is a long-lived background process that reduces the time it takes to run a build.

The Gradle Daemon reduces build times by:

Caching project information across builds
Running in the background so every Gradle build doesn’t have to wait for JVM startup
Benefiting from continuous runtime optimization in the JVM
Watching the file system to calculate exactly what needs to be rebuilt before you run a build

The Gradle Client sends the Gradle Daemon build information such as command line arguments, project directories, and environment variables so that it can run the build. The Daemon is responsible for resolving dependencies, executing build scripts, creating and running tasks; when it is done, it sends the client the output. Communication between the client and the Daemon happens via a local socket connection.

Daemons use the JVM’s default minimum heap size.

If the requested build environment does not specify a maximum heap size, the Daemon uses up to 512MB of heap. 512MB is adequate for most builds. Larger builds with hundreds of subprojects, configuration, and source code may benefit from a larger heap size.

Check Daemon status

To get a list of running Daemons and their statuses, use the --status command:

$ gradle --status

   PID STATUS   INFO
 28486 IDLE     7.5
 34247 BUSY     7.5

Currently, a given Gradle version can only connect to Daemons of the same version. This means the status output only shows Daemons spawned running the same version of Gradle as the current project.

Find Daemons

If you have installed the Java Development Kit (JDK), you can view live daemons with the jps command.

$ jps

33920 Jps
27171 GradleDaemon
22792

Live Daemons appear under the name GradleDaemon. Because this command uses the JDK, you can view Daemons running any version of Gradle.

Enable Daemon

Gradle enables the Daemon by default since Gradle 3.0. If your project doesn’t use the Daemon, you can enable it for a single build with the --daemon flag when you run a build:

$ gradle <task> --daemon

This flag overrides any settings that disable the Daemon in your project or user gradle.properties files.

To enable the Daemon by default in older Gradle versions, add the following setting to the gradle.properties file in the project root or your Gradle User Home (GRADLE_USER_HOME):

gradle.properties

org.gradle.daemon=true

Disable Daemon

You can disable the Daemon in multiple ways but there are important considerations:

Single-use Daemon: If the JVM args of the client process don’t match what the build requires, a single-used Daemon (disposable JVM) is created. This means the Daemon is required for the build, so it is created, used, and then stopped at the end of the build.
No Daemon: If the JAVA_OPTS and GRADLE_OPTS match org.gradle.jvmargs, the Daemon will not be used at all since the build happens in the client JVM.

Disable for a build

To disable the Daemon for a single build, pass the --no-daemon flag when you run a build:

$ gradle <task> --no-daemon

This flag overrides any settings that enable the Daemon in your project including the gradle.properties files.

Disable for a project

To disable the Daemon for all builds of a project, add org.gradle.daemon=false to the gradle.properties file in the project root.

Disable for a user

On Windows, this command disables the Daemon for the current user:

(if not exist "%USERPROFILE%/.gradle" mkdir "%USERPROFILE%/.gradle") && (echo. >> "%USERPROFILE%/.gradle/gradle.properties" && echo org.gradle.daemon=false >> "%USERPROFILE%/.gradle/gradle.properties")

On UNIX-like operating systems, the following Bash shell command disables the Daemon for the current user:

mkdir -p ~/.gradle && echo "org.gradle.daemon=false" >> ~/.gradle/gradle.properties

Disable globally

There are two recommended ways to disable the Daemon globally across an environment:

add org.gradle.daemon=false to the $GRADLE_USER_HOME/gradle.properties` file
add the flag -Dorg.gradle.daemon=false to the GRADLE_OPTS environment variable

Don’t forget to make sure your JVM arguments and GRADLE_OPTS / JAVA_OPTS match if you want to completely disable the Daemon and not simply invoke a single-use one.

Stop Daemon

It can be helpful to stop the Daemon when troubleshooting or debugging a failure.

Daemons automatically stop given any of the following conditions:

Available system memory is low
Daemon has been idle for 3 hours

To stop running Daemon processes, use the following command:

$ gradle --stop

This terminates all Daemon processes started with the same version of Gradle used to execute the command.

You can also kill Daemons manually with your operating system. To find the PIDs for all Daemons regardless of Gradle version, see Find Daemons.

Troubleshooting the Daemon

The Gradle Daemon is a long-lived background process, as such, it can sometimes encounter issues.

If builds start behaving unexpectedly, try stopping and restarting the Daemon:

$ gradle --stop

If you see a warning like: Multiple Gradle daemons might be spawned because the Gradle JDK and JAVA_HOME locations are different.

Gradle is telling you that it’s using more than one Java version across your environment. This can lead to multiple daemons being started, increasing memory usage unnecessarily.

To resolve this, make sure your Java versions match across:

Your environment (JAVA_HOME)
Your build script (if using toolchains)
Your IDE’s configured JDK

To check JAVA_HOME, run this in your terminal:

echo $JAVA_HOME

Your project may be using a specific toolchain in your build.gradle(.kts) file. Check for similar code:

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(11)
    }
}

If your build uses a toolchain, ensure it matches the JAVA_HOME value, or at least know they differ intentionally. You should also check your IDE settings to make sure they match as well.

Daemon Logs

The Gradle Daemon writes detailed log files to help diagnose build issues and understand daemon behavior.

These logs are stored in the Gradle User Home directory under daemon/<gradle-version>/:

~/.gradle/daemon/9.4.0/
├── daemon-<pid>.out.log
├── daemon-<pid>.out.log
└── registry.bin

Each daemon process creates its own log file named daemon-<pid>.out.log, where <pid> is the process ID of that daemon instance.

Automatic Log Cleanup

Gradle automatically cleans up old daemon logs to prevent the daemon directory from growing indefinitely.

By default, daemon logs older than 14 days are deleted during build execution as part of Gradle’s periodic cache cleanup. This cleanup runs alongside other cache cleanup operations.

The cleanup is triggered during builds:

In the background between builds when using the daemon (default behavior)
In the foreground after the build when using --no-daemon

The 14-day retention period for daemon logs can be configured via an init script, just like other cache retention periods. See Configuring cleanup of caches and distributions for configuration examples.

Daemon JVM Toolchains

By default, the Gradle Daemon runs with the same JVM installation that started the build. Gradle defaults to the current shell path and JAVA_HOME environment variable to locate a usable JVM.

Alternatively, a different JVM installation can be specified for the build using the org.gradle.java.home Gradle property or programmatically through the Tooling API.

Building on the toolchain feature, you can now use declarative criteria to specify the JVM requirements for the build.

If the Daemon JVM criteria configuration is provided, it takes precedence over JAVA_HOME and org.gradle.java.home.

Daemon JVM criteria

The Daemon JVM criteria is controlled by the updateDaemonJvm task, similar to how the wrapper task updates the wrapper properties file.

Warning

This process requires toolchain download repositories to be configured. See below for details.

When the task runs, it creates or updates the criteria in the gradle/gradle-daemon-jvm.properties file.

To configure the generation, you can use command line options:

$ ./gradlew updateDaemonJvm --jvm-version=17

Or configure the task in the build script of the root project:

build.gradle.kts

tasks.named<UpdateDaemonJvm>("updateDaemonJvm") {
    languageVersion = JavaLanguageVersion.of(17)
}

build.gradle

tasks.named("updateDaemonJvm") {
    languageVersion = JavaLanguageVersion.of(17)
}

And then run the task:

$ ./gradlew updateDaemonJvm

Both of these actions will produce a file like the following one:

gradle/gradle-daemon-jvm.properties

#This file is generated by updateDaemonJvm
toolchainUrl.FREE_BSD.AARCH64=https\://example.com/...
toolchainUrl.FREE_BSD.X86_64=https\://example.com/...
toolchainUrl.LINUX.AARCH64=https\://example.com/...
toolchainUrl.LINUX.X86_64=https\://example.com/...
toolchainUrl.MAC_OS.AARCH64=https\://example.com/...
toolchainUrl.MAC_OS.X86_64=https\://example.com/...
toolchainUrl.UNIX.AARCH64=https\://example.com/...
toolchainUrl.UNIX.X86_64=https\://example.com/...
toolchainUrl.WINDOWS.X86_64=https\://example.com/...
toolchainVersion=17

If you run the updateDaemonJvm task without any arguments, and the properties file does not exist, then the version of the current JVM used by the Daemon will be used.

On the next execution of the build, the Gradle client will use this file to locate a compatible JVM installation and start the Daemon with it.

Similar to the wrapper, the generated gradle-daemon-jvm.properties file should be checked into version control. This ensures that any developer or CI server running the build will use the same JVM version.

Specifying a JVM vendor

The JVM vendor, like the JVM version, can be used as a criteria to select a compatible JVM installation for the build. If no vendor is specified, Gradle considers all vendors compatible.

By default, running updateDaemonJvm to create the gradle-daemon-jvm.properties file will not generate a JVM vendor criteria. To specify a vendor, either configure it in the build script, using the same syntax as the Java toolchain spec, or pass it on the command line:

$ ./gradlew updateDaemonJvm --jvm-version=17 --jvm-vendor=adoptium

List of recognized vendors:

Known Vendors Acceptable Strings toolchainVendor Value

Adoptium / Eclipse Temurin

adoptium, temurin, eclipse foundation

ADOPTIUM

AdoptOpenJDK

adoptopenjdk, aoj

ADOPTOPENJDK

Amazon Corretto

amazon, corretto

AMAZON

Apple

apple

APPLE

Azul Zulu

azul, zulu

AZUL

BellSoft

bellsoft, liberica

BELLSOFT

GraalVM

graalvm, graal vm

GRAAL_VM

Hewlett Packard

hp, hewlett

HEWLETT_PACKARD

IBM

ibm, semeru, international business machines corporation

IBM

JetBrains

jetbrains, jbr

JETBRAINS

Microsoft

microsoft

MICROSOFT

Oracle

oracle

ORACLE

SAP

sap

SAP

Tencent

tencent, kona

TENCENT

Some vendors will be recognized from more than one set of characters. All vendor strings are case-insensitive. You can view the list of recognized vendors by running ./gradlew help --task updateDaemonJvm.

If the specified vendor is not one of the recognized equivalents, Gradle will match it exactly. For example, "MyCustomJVM" would require an exact match of the vendor name.

Requesting a native-image capable JDK

Both the CLI options and the task configuration allow to request a JDK that is native-image capable.

$ ./gradlew updateDaemonJvm --jvm-version=17 --native-image-capable

See the toolchain documentation section for more information.

Auto-detection and auto-provisioning

The Daemon JVM is auto-detected using the same logic as project JVM toolchains.

With auto-provisioning, the logic is simpler, as Gradle can only look up a download URL matching the platform inside the gradle-daemon-jvm.properties file. The URL is then used to download a JDK if none can be found locally.

The properties used for disabling auto-detection and auto-provisioning affect the Daemon toolchain resolution logic:

org.gradle.java.installations.auto-detect=false
org.gradle.java.installations.auto-download=false

Configuring provisioning URLs

Note	There are currently no CLI options for configuring this.

By default, the updateDaemonJvm task attempts to generate download URLs for JDKs on various platforms (OS and architecture) that match the specified criteria. Gradle needs to consider more than the current running platform as the build could be run on different platforms.

Gradle sets, by convention, build platforms based on architectures X86_64 and AARCH64 for the following operating systems:

These platforms can be configured through the toolchainPlatforms property of the UpdateDaemonJvm task.

build.gradle.kts

tasks.named<UpdateDaemonJvm>("updateDaemonJvm") {
    val myPlatforms = mutableListOf(
        BuildPlatformFactory.of(
            org.gradle.platform.Architecture.AARCH64,
            org.gradle.platform.OperatingSystem.MAC_OS
        )
    )
    toolchainPlatforms.set(myPlatforms)
}

build.gradle

tasks.named("updateDaemonJvm") {
    def myPlatforms = [
        BuildPlatformFactory.of(
            org.gradle.platform.Architecture.AARCH64,
            org.gradle.platform.OperatingSystem.MAC_OS
        )
    ]
    toolchainPlatforms.set(myPlatforms)
}

Gradle resolves JDK download URLs for these platforms by using the configured toolchain download repositories. If no such repositories are configured and the toolchainPlatforms property has at least one value, the updateDaemonJvm task will fail.

Alternatively, users can directly configure the JDK URLs for specific platforms using the toolchainDownloadUrls property. This property is a Map<BuildPlatform, URI> and can be configured as shown in the following example:

build.gradle.kts

tasks.named<UpdateDaemonJvm>("updateDaemonJvm") {
    toolchainDownloadUrls = mapOf(
        BuildPlatformFactory.of(org.gradle.platform.Architecture.AARCH64, org.gradle.platform.OperatingSystem.MAC_OS) to uri("https://server?platform=MAC_OS.AARCH64"),
        BuildPlatformFactory.of(org.gradle.platform.Architecture.AARCH64, org.gradle.platform.OperatingSystem.WINDOWS) to uri("https://server?platform=WINDOWS.AARCH64")
    )
}

build.gradle

tasks.named("updateDaemonJvm") {
    toolchainDownloadUrls = [(BuildPlatformFactory.of(org.gradle.platform.Architecture.AARCH64, org.gradle.platform.OperatingSystem.MAC_OS)) : uri("https://server?platform=MAC_OS.AARCH64"),
                             (BuildPlatformFactory.of(org.gradle.platform.Architecture.AARCH64, org.gradle.platform.OperatingSystem.WINDOWS)) : uri("https://server?platform=WINDOWS.AARCH64")]
}

Tip	A full package name is required for `org.gradle.platform.Architecture` and `org.gradle.platform.OperatingSystem` due to a naming conflict with other types in different packages, which are resolved first alphabetically.

Running ./gradlew updateDaemonJvm produces the following:

#This file is generated by updateDaemonJvm
toolchainUrl.MAC_OS.AARCH64=https\://server?platform\=MAC_OS.AARCH64
toolchainUrl.WINDOWS.AARCH64=https\://server?platform\=WINDOWS.AARCH64
toolchainVersion=17

If you want to disable the generation of URLs by the updateDaemonJvm task:

build.gradle.kts

tasks.named<UpdateDaemonJvm>("updateDaemonJvm") {
    toolchainDownloadUrls.empty()
}

build.gradle

tasks.named("updateDaemonJvm") {
    toolchainPlatforms = []
}

Removing all platforms means that there is no longer a need for the toolchain download repositories to be configured.

Tools & IDEs

The Gradle Tooling API used by IDEs and other tools to integrate with Gradle always uses the Gradle Daemon to execute builds. If you execute Gradle builds from within your IDE, you already use the Gradle Daemon. There is no need to enable it for your environment.

Continuous Integration

We recommend using the Daemon for developer machines and Continuous Integration (CI) servers.

Compatibility

Gradle starts a new Daemon if no idle or compatible Daemons exist.

The following values determine compatibility:

Requested build environment, including the following:
- Java version
- JVM attributes
- JVM properties
Gradle version

Compatibility is based on exact matches of these values. For example:

If a Daemon is available with a Java 8 runtime, but the requested build environment calls for Java 10, then the Daemon is not compatible.
If a Daemon is available running Gradle 7.0, but the current build uses Gradle 7.4, then the Daemon is not compatible.

Certain properties of a Java runtime are immutable: they cannot be changed once the JVM has started. The following JVM system properties are immutable:

file.encoding
user.language
user.country
user.variant
java.io.tmpdir
javax.net.ssl.keyStore
javax.net.ssl.keyStorePassword
javax.net.ssl.keyStoreType
javax.net.ssl.trustStore
javax.net.ssl.trustStorePassword
javax.net.ssl.trustStoreType
com.sun.management.jmxremote

The following JVM attributes controlled by startup arguments are also immutable:

The maximum heap size (the -Xmx JVM argument)
The minimum heap size (the -Xms JVM argument)
The boot classpath (the -Xbootclasspath argument)
The "assertion" status (the -ea argument)

If the requested build environment requirements for any of these properties and attributes differ from the Daemon’s JVM requirements, the Daemon is not compatible.

Note	For more information about build environments, see the build environment documentation.

Performance Impact

The Daemon can reduce build times by 15-75% when you build the same project repeatedly.

In between builds, the Daemon waits idly for the next build. As a result, your machine only loads Gradle into memory once for multiple builds instead of once per build. This is a significant performance optimization.

Runtime Code Optimizations

The JVM gains significant performance from runtime code optimization: optimizations applied to code while it runs.

JVM implementations like OpenJDK’s Hotspot progressively optimize code during execution. Consequently, subsequent builds can be faster purely due to this optimization process.

With the Daemon, perceived build times can drop dramatically between a project’s 1^st and 10^th builds.

Memory Caching

The Daemon enables in-memory caching across builds. This includes classes for plugins and build scripts.

Similarly, the Daemon maintains in-memory caches of build data, such as the hashes of task inputs and outputs for incremental builds.

Performance Monitoring

Gradle actively monitors heap usage to detect memory leaks in the Daemon.

When a memory leak exhausts available heap space, the Daemon:

Finishes the currently running build.
Restarts before running the next build.

Gradle enables this monitoring by default.

To disable this monitoring, set the org.gradle.daemon.performance.enable-monitoring Daemon option to false.

You can do this on the command line with the following command:

$ gradle <task> -Dorg.gradle.daemon.performance.enable-monitoring=false

Or you can configure the property in the gradle.properties file in the project root or your GRADLE_USER_HOME (Gradle User Home):

gradle.properties

org.gradle.daemon.performance.enable-monitoring=false

Gradle-managed Directories and Caches

Gradle uses two main directories to perform and manage its work and stores several caches under them:

1. Gradle User Home directory

By default, the Gradle User Home (~/.gradle or C:\Users\<USERNAME>\.gradle) stores global configuration properties, initialization scripts, caches, and log files.

It can be set with the environment variable GRADLE_USER_HOME.

Tip	Not to be confused with the `GRADLE_HOME`, the optional installation directory for Gradle.

It is roughly structured as follows:

├── caches              // (1)
├── daemon              // (2)
├── init.d              // (3)
├── jdks                // (4)
├── wrapper
│   └── dists           // (5)
└── gradle.properties   // (6)

Caches.
Registry and logs of the Gradle Daemon.
Global initialization scripts.
JDKs downloaded by the toolchain support.
Distributions downloaded by the Gradle Wrapper.
Global Gradle configuration properties.

2. Project Root directory

The project root directory contains all source files from your project.

It also contains files and directories Gradle generates, such as .gradle and build.

While the former are usually checked into source control, the latter are transient files Gradle uses to support features like incremental builds.

The anatomy of a typical project root directory looks as follows:

├── .gradle                 // (1)
├── build                   // (2)
├── gradle
│   └── wrapper             // (3)
├── gradle.properties       // (4)
├── gradlew                 // (5)
├── gradlew.bat             // (5)
├── settings.gradle.kts     // (6)
├── subproject-one          // (7)
|   └── build.gradle.kts    // (8)
├── subproject-two          // (7)
|   └── build.gradle.kts    // (8)
└── ⋮

Project-specific cache directory generated by Gradle.
The build directory of this project into which Gradle generates all build artifacts.
Contains the JAR file and configuration of the Gradle Wrapper.
Project-specific Gradle configuration properties.
Scripts for executing builds using the Gradle Wrapper.
The project’s settings file where the list of subprojects is defined.
Usually, a project is organized into one or multiple subprojects.
Each subproject has its own Gradle build script.

3. Caches

Gradle uses several on-disk caches to make repeat builds faster. These caches live under the directories described in Gradle User Home and Project Root. In most cases they do not require manual management. Gradle creates, uses, and cleans them automatically.

Version-specific caches

These caches live under caches/<gradle-version>/ in the Gradle User Home and are tied to a specific Gradle release. They are recreated on first use of that Gradle version.

Directory Contents

<version>/generated-gradle-jars

JARs that Gradle generates on first use of the Gradle version.

<version>/kotlin-dsl

Compiled Kotlin DSL scripts and accessors.

<version>/scripts

Compiled Groovy DSL scripts.

Shared caches

These caches live directly under caches/ in the Gradle User Home and are shared across Gradle versions. The trailing number in each directory name is the on-disk format version; see Format versions in cache directory names.

Directory Contents

build-cache-1

Local Build Cache entries: task outputs keyed by input hashes.

jars-9

Instrumented JARs produced by Gradle’s classpath instrumentation.

modules-2

Downloaded module dependencies (POMs, JARs, metadata). See Dependency caching.

transforms-3

Outputs of artifact transforms.

Project-local caches

These caches live under .gradle/ in the project root and are specific to a single project.

Directory Contents

.gradle/<version>

Version-specific build state for incremental build (snapshots of task inputs and outputs from the previous build).

.gradle/configuration-cache

Configuration Cache state for this project: the serialized task graph, configuration inputs, and metadata used to skip the configuration phase on subsequent builds.

Format versions in cache directory names

Several caches use a trailing format version in their directory name (for example, modules-2, jars-9, transforms-3, build-cache-1). The number changes when Gradle changes the on-disk layout for that cache.

When multiple format versions of the same cache exist on disk (for example, both transforms-3 and transforms-4), the older one is left behind from a previous Gradle version and is cleaned up after the inactivity threshold. Only the current format is being written by the current Gradle version.

Cleanup of caches and distributions

Gradle automatically cleans its caches in both the Gradle User Home and the project directory.

By default, the cleanup runs in the background when the Gradle daemon is stopped or shut down.

If using --no-daemon, it runs in the foreground after the build session.

Gradle User Home cleanup

The following cleanup strategies are applied periodically (by default, once every 24 hours):

Version-specific caches in all caches/<GRADLE_VERSION>/ directories are checked for whether they are still in use.

If not, directories for release versions are deleted after 30 days of inactivity, and snapshot versions after 7 days.
Shared caches in caches/ (e.g., jars-*) are checked for whether they are still in use.

If no Gradle version still uses them, they are deleted.
Files in shared caches used by the current Gradle version in caches/ (e.g., jars-9 or modules-2) are checked for when they were last accessed.

Depending on whether the file can be recreated locally or downloaded from a remote repository, it will be deleted after 7 or 30 days, respectively.
Gradle distributions in wrapper/dists/ are checked for whether they are still in use, i.e., whether there’s a corresponding version-specific cache directory.

Unused distributions are deleted.
Daemon log files in daemon/<GRADLE_VERSION>/ directories are checked for their last modification time.

Log files older than 14 days are automatically deleted to prevent the daemon directory from growing indefinitely.

Project cache cleanup

From version 4.10 onwards, Gradle automatically cleans the project-specific cache directory.

After building the project, version-specific cache directories in .gradle/9.7.0/ are checked periodically (at most, every 24 hours) to determine whether they are still in use. They are deleted if they haven’t been used for 7 days.

Configuring cleanup of caches and distributions

The retention periods of the various caches can be configured.

Caches are classified into six categories:

Released wrapper distributions: Distributions and related version-specific caches corresponding to released versions (e.g., 4.6.2 or 8.0).

Default retention for unused versions is 30 days.
Snapshot wrapper distributions: Distributions and related version-specific caches corresponding to snapshot versions (e.g. 7.6-20221130141522+0000).

Default retention for unused versions is 7 days.
Downloaded resources: Shared caches downloaded from a remote repository (e.g., cached dependencies).

Default retention for unused resources is 30 days.
Created resources: Shared caches that Gradle creates during a build (e.g., artifact transforms).

Default retention for unused resources is 7 days.
Build cache: The local build cache (e.g., build-cache-1).

Default retention for unused build cache entries is 7 days.
Daemon logs: Log files from Gradle Daemon processes in daemon/<GRADLE_VERSION>/ directories.

Default retention for daemon logs is 14 days.

The retention period for each category can be configured independently via an init script in the Gradle User Home:

gradleUserHome/init.d/cache-settings.init.gradle.kts

beforeSettings {
    caches {
        releasedWrappers.setRemoveUnusedEntriesAfterDays(45)
        snapshotWrappers.setRemoveUnusedEntriesAfterDays(10)
        downloadedResources.setRemoveUnusedEntriesAfterDays(45)
        createdResources.setRemoveUnusedEntriesAfterDays(10)
        buildCache.setRemoveUnusedEntriesAfterDays(5)
        daemonLogs.setRemoveUnusedEntriesAfterDays(14)
    }
}

gradleUserHome/init.d/cache-settings.init.gradle

beforeSettings { settings ->
    settings.caches {
        releasedWrappers.removeUnusedEntriesAfterDays = 45
        snapshotWrappers.removeUnusedEntriesAfterDays = 10
        downloadedResources.removeUnusedEntriesAfterDays = 45
        createdResources.removeUnusedEntriesAfterDays = 10
        buildCache.removeUnusedEntriesAfterDays = 5
        daemonLogs.removeUnusedEntriesAfterDays = 14
    }
}

The frequency at which cache cleanup is invoked is also configurable.

There are three possible settings:

DEFAULT: Cleanup is performed periodically in the background (currently once every 24 hours).
DISABLED: Never cleanup Gradle User Home.

This is useful in cases where Gradle User Home is ephemeral or delaying cleanup is desirable until an explicit point.
ALWAYS: Cleanup is performed at the end of each build session.

This is useful in cases where it’s desirable to ensure that cleanup has occurred before proceeding.

However, this performs cache cleanup during the build (rather than in the background), which can be expensive, so this option should only be used when necessary.

To disable cache cleanup:

gradleUserHome/init.d/cache-settings.init.gradle.kts

beforeSettings {
    caches {
        cleanup = Cleanup.DISABLED
    }
}

gradleUserHome/init.d/cache-settings.init.gradle

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

Note

Cache cleanup settings can only be configured via init scripts and should be placed under the init.d directory in Gradle User Home. This effectively couples the configuration of cache cleanup to the Gradle User Home those settings apply to and limits the possibility of different conflicting settings from different projects being applied to the same directory.

Multiple versions of Gradle sharing a Gradle User Home

It is common to share a single Gradle User Home between multiple versions of Gradle.

As stated above, caches in Gradle User Home are version-specific. Different versions of Gradle will perform maintenance on only the version-specific caches associated with each version.

On the other hand, some caches are shared between versions (e.g., the dependency artifact cache or the artifact transform cache).

Beginning with Gradle version 8.0, the cache cleanup settings can be configured to custom retention periods. However, older versions have fixed retention periods (7 or 30 days, depending on the cache). These shared caches could be accessed by versions of Gradle with different settings to retain cache artifacts.

This means that:

If the retention period is not customized, all versions that perform cleanup will have the same retention periods. There will be no effect due to sharing a Gradle User Home with multiple versions.
If the retention period is customized for Gradle versions greater than or equal to version 8.0 to use retention periods shorter than the previously fixed periods, there will also be no effect.

The versions of Gradle aware of these settings will cleanup artifacts earlier than the previously fixed retention periods, and older versions will effectively not participate in the cleanup of shared caches.
If the retention period is customized for Gradle versions greater than or equal to version 8.0 to use retention periods longer than the previously fixed periods, the older versions of Gradle may clean the shared caches earlier than what is configured.

In this case, if it is desirable to maintain these shared cache entries for newer versions for longer retention periods, they will not be able to share a Gradle User Home with older versions. They will need to use a separate directory.

Another consideration when sharing the Gradle User Home with versions of Gradle before version 8.0 is that the DSL elements to configure the cache retention settings are unavailable in earlier versions, so this must be accounted for in any init script shared between versions. This can easily be handled by conditionally applying a version-compliant script.

Note	The version-compliant script should reside somewhere other than the `init.d` directory (such as a sub-directory), so it is not automatically applied.

To configure cache cleanup in a version-safe manner:

gradleUserHome/init.d/cache-settings.init.gradle.kts

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

gradleUserHome/init.d/cache-settings.init.gradle

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

Version-compliant cache configuration script:

gradleUserHome/init.d/gradle8/cache-settings.init.gradle.kts

beforeSettings {
    caches {
        releasedWrappers { setRemoveUnusedEntriesAfterDays(45) }
        snapshotWrappers { setRemoveUnusedEntriesAfterDays(10) }
        downloadedResources { setRemoveUnusedEntriesAfterDays(45) }
        createdResources { setRemoveUnusedEntriesAfterDays(10) }
        buildCache { setRemoveUnusedEntriesAfterDays(5) }
    }
}

gradleUserHome/init.d/gradle8/cache-settings.init.gradle

beforeSettings { settings ->
    settings.caches {
        releasedWrappers.removeUnusedEntriesAfterDays = 45
        snapshotWrappers.removeUnusedEntriesAfterDays = 10
        downloadedResources.removeUnusedEntriesAfterDays = 45
        createdResources.removeUnusedEntriesAfterDays = 10
        buildCache.removeUnusedEntriesAfterDays = 5
    }
}

Cache marking

Beginning with Gradle version 8.1, Gradle supports marking caches with a CACHEDIR.TAG file.

It follows the format described in the Cache Directory Tagging Specification. The purpose of this file is to allow tools to identify the directories that do not need to be searched or backed up.

By default, the directories caches, wrapper/dists, daemon, and jdks in the Gradle User Home are marked with this file.

Configuring cache marking

The cache marking feature can be configured via an init script in the Gradle User Home:

gradleUserHome/init.d/cache-settings.init.gradle.kts

beforeSettings {
    caches {
        // Disable cache marking for all caches
        markingStrategy = MarkingStrategy.NONE
    }
}

gradleUserHome/init.d/cache-settings.init.gradle

beforeSettings { settings ->
    settings.caches {
        // Disable cache marking for all caches
        markingStrategy = MarkingStrategy.NONE
    }
}

Note

Cache marking settings can only be configured via init scripts and should be placed under the init.d directory in Gradle User Home. This effectively couples the configuration of cache marking to the Gradle User Home to which those settings apply and limits the possibility of different conflicting settings from different projects being applied to the same directory.

Build Environment Configuration

Configuring the build environment is a powerful way to customize the build process. There are many mechanisms available. By leveraging these mechanisms, you can make your Gradle builds more flexible and adaptable to different environments and requirements.

Available mechanisms

Gradle provides multiple mechanisms for configuring the behavior of Gradle itself and specific projects:

Mechanism Information Example

Command line interface

Flags that configure build behavior and Gradle features

--rerun

Project properties

Properties specific to your Gradle project

TestFilter::isFailOnNoMatchingTests=false

System properties

Properties that are passed to the Gradle runtime (JVM)

http.proxyHost=somehost.org

Gradle properties

Properties that configure Gradle settings and the Java process that executes your build

org.gradle.logging.level=quiet

Environment variables

Properties that configure build behavior based on the environment

JAVA_HOME

Priority for configurations

When configuring Gradle behavior, you can use these methods, but you must consider their priority.

Gradle reads gradle.properties configurations in the following order (highest precedence first):

Priority Method Location Notes

Command-line

> Command line

Flags have precedence over properties and environment variables

System properties

> Project Root Dir

Stored in a gradle.properties file

Gradle properties

> GRADLE_USER_HOME
> Project Root Dir
> GRADLE_HOME

Stored in a gradle.properties file

Environment variables

> Environment

Sourced by the environment that executes Gradle

Here are all possible configurations of specifying the JDK installation directory in order of priority:

Command Line

$ ./gradlew exampleTask -Dorg.gradle.java.home=/path/to/your/java/home --scan

Gradle Properties File

gradle.properties

org.gradle.java.home=/path/to/your/java/home

Environment Variable

$ export JAVA_HOME=/path/to/your/java/home

The `gradle.properties` file

Gradle properties, system properties, and project properties can be found in the gradle.properties file:

gradle.properties

# Gradle properties
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.jvmargs=-Duser.language=en -Duser.country=US -Dfile.encoding=UTF-8

# System properties
systemProp.pts.enabled=true
systemProp.log4j2.disableJmx=true
systemProp.file.encoding = UTF-8

# Project properties
kotlin.code.style=official
android.nonTransitiveRClass=false
spring-boot.version = 2.2.1.RELEASE

You can place the gradle.properties file in the root directory of your project, the Gradle user home directory (GRADLE_USER_HOME), or the directory where Gradle is optionally installed (GRADLE_HOME).

When resolving properties, Gradle first looks in the user-level gradle.properties file located in GRADLE_USER_HOME, then in the project-level gradle.properties file, and finally in the gradle.properties file located in GRADLE_HOME, with user-level properties taking precedence over project-level and installation-level properties.

Note	See our Best Practice recommendation on where to locate `gradle.properties` for further guidance.

Project properties

Project properties are specific to your Gradle project, they can be used to customize your build. Project properties can be accessed in your build files and get passed in from an external source when your build is executed. Project properties can be retrieved in build scripts lazily using providers.gradleProperty().

Setting a project property

You have four options to add project properties, listed in order of priority:

Command Line: You can add project properties directly to your Project object via the -P command line option.
```
$ ./gradlew build -PmyProperty='Hi, world'
```
System Property: Gradle creates specially-named system properties for project properties which you can set using the -D command line flag or gradle.properties file. For the project property myProperty, the system property created is called org.gradle.project.myProperty.
```
$ ./gradlew build -Dorg.gradle.project.myProperty='Hi, world'
```
gradle.properties
```
org.gradle.project.myProperty='Hi, world'
```
Gradle Properties File: You can also set project properties in gradle.properties files.
gradle.properties
```
myProperty='Hi, world'
```
The gradle.properties file can be located in a number of places, including <GRADLE_USER_HOME>/gradle.properties, ./gradle.properties (the project root) and <GRADLE_HOME>/gradle.properties.

If the same property is defined in multiple locations, the file’s location determines its precedence.
Environment Variables: You can set project properties with environment variables. If the environment variable name looks like ORG_GRADLE_PROJECT_myProperty='Hi, world', then Gradle will set a myProperty property on your project object, with the value of Hi, world.
```
$ export ORG_GRADLE_PROJECT_myProperty='Hi, world'
```
This is typically the preferred method for supplying project properties, especially secrets, to unattended builds like those running on CI servers.

Accessing a project property

The recommended way to access a project property is through the Provider API:

val myProperty: Provider<String> = providers.gradleProperty("myProperty")

The returned Provider is lazy and compatible with the Configuration Cache. The provider resolves the property from the build-level sources listed above: command-line -P arguments, org.gradle.project.* system properties, ORG_GRADLE_PROJECT_* environment variables, and gradle.properties files in the Gradle User Home, build root, and Gradle installation directories.

Note	`providers.gradleProperty()` does not include properties from `gradle.properties` files in subproject directories, nor extra properties or other properties set dynamically on individual `Project` instances. To access those, use `project.findProperty("name")` or extra properties directly.

For other ways to access properties, see the following methods on the Project object:

findProperty("name") — returns the value or null, checking dynamically configured containers, like extra properties, and parent projects as well.
property("name") — returns the value or throws if the property is missing
hasProperty("name") — checks if the property exists

It is possible to change the behavior of a task based on project properties specified at invocation time. Suppose you’d like to ensure release builds are only triggered by CI. A simple way to handle this is through an isCI project property:

build.gradle.kts

tasks.register("performRelease") {
    val isCI = providers.gradleProperty("isCI")
    doLast {
        if (isCI.isPresent) {
            println("Performing release actions")
        } else {
            throw InvalidUserDataException("Cannot perform release outside of CI")
        }
    }
}

build.gradle

tasks.register('performRelease') {
    def isCI = providers.gradleProperty("isCI")
    doLast {
        if (isCI.present) {
            println("Performing release actions")
        } else {
            throw new InvalidUserDataException("Cannot perform release outside of CI")
        }
    }
}

$ ./gradlew performRelease -PisCI=true --quiet

Performing release actions

Note that running ./gradlew performRelease yields the same results as long as your gradle.properties file includes isCI=true:

gradle.properties

isCI=true

$ ./gradlew performRelease --quiet

Performing release actions

Command-line flags

The command line interface and the available flags are described in its own section.

System properties

System properties are variables set at the JVM level and accessible to the Gradle build process. System properties can be retrieved in build scripts lazily using providers.systemProperty().

Setting a system property

You have two options to add system properties listed in order of priority:

Command Line: Using the -D command-line option, you can pass a system property to the JVM, which runs Gradle. The -D option of the gradle command has the same effect as the -D option of the java command.
```
$ ./gradlew build -Dgradle.wrapperUser=myuser
```
Gradle Properties File: You can also set system properties in gradle.properties files with the prefix systemProp.
gradle.properties
```
systemProp.gradle.wrapperUser=myuser
```

System properties reference

For a quick reference, the following are common system properties:

gradle.wrapperUser=(myuser): Specify username to download Gradle distributions from servers using HTTP Basic Authentication.
gradle.wrapperPassword=(mypassword): Specify password for downloading a Gradle distribution using the Gradle wrapper.
gradle.user.home=(path to directory): Specify the GRADLE_USER_HOME directory.
https.protocols: Specify the supported TLS versions in a comma-separated format. e.g., TLSv1.2,TLSv1.3.

Additional Java system properties are listed here.

In a multi-project build, systemProp properties set in any project except the root will be ignored. Only the root project’s gradle.properties file will be checked for properties that begin with systemProp.

Gradle properties

Gradle properties configure Gradle itself and usually have the name org.gradle.*. Gradle properties should not be used in build logic, their values should not be read/retrieved in build scripts.

Setting a Gradle property

You have two options to add Gradle properties listed in order of priority:

Command Line: Using the -D command-line option, you can pass a Gradle property:
```
$ ./gradlew build -Dorg.gradle.caching.debug=false
```
Gradle Properties File: Place these settings into a gradle.properties file and commit it to your version control system.
gradle.properties
```
org.gradle.caching.debug=false
```

The final configuration considered by Gradle is a combination of all Gradle properties set on the command line and your gradle.properties files. If an option is configured in multiple locations, the first one found in any of these locations wins:

Priority Method Location Details

Command line interface

In the command line using -D.

gradle.properties file

GRADLE_USER_HOME

Stored in a gradle.properties file in the GRADLE_USER_HOME.

gradle.properties file

Project Root Dir

Stored in a gradle.properties file in a project directory, then its parent project’s directory up to the project’s root directory.

gradle.properties file

GRADLE_HOME

Stored in a gradle.properties file in the GRADLE_HOME, the optional Gradle installation directory.

Note	The location of the `GRADLE_USER_HOME` may have been changed beforehand via the `-Dgradle.user.home` system property passed on the command line.

Gradle properties reference

For reference, the following properties are common Gradle properties:

org.gradle.caching=(true,false): When set to true, Gradle will reuse task outputs from any previous build when possible, resulting in much faster builds.

Default is false; the build cache is not enabled.
org.gradle.caching.debug=(true,false): When set to true, individual input property hashes and the build cache key for each task are logged on the console.

Default is false.
org.gradle.configuration-cache=(true,false): Enables configuration caching. Gradle will try to reuse the build configuration from previous builds.

Default is false.
org.gradle.configureondemand=(true,false): Enables incubating configuration-on-demand, where Gradle will attempt to configure only necessary projects.

Default is false.
org.gradle.console=(auto,plain,colored,rich,verbose): Customize console output coloring or verbosity.

Default depends on how Gradle is invoked.
org.gradle.console.interactive=(true,false) Incubating: When set to false, Gradle does not prompt the user for input on the console and uses default values instead. This is useful for automated environments such as CI pipelines, scripts, and AI agents.

Default is true.
org.gradle.continue=(true,false): If enabled, continue task execution after a task failure, else stop task execution after a task failure.

Default is false.
org.gradle.daemon=(true,false): When set to true the Gradle Daemon is used to run the build.

Default is true.
org.gradle.daemon.idletimeout=(# of idle millis): Gradle Daemon will terminate itself after a specified number of idle milliseconds.

Default is 10800000 (3 hours).
org.gradle.debug=(true,false): When set to true, Gradle will run the build with remote debugging enabled, listening on port 5005. Note that this is equivalent to adding -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005 to the JVM command line and will suspend the virtual machine until a debugger is attached.

Default is false.
org.gradle.java.home=(path to JDK home): Specifies the Java home for the Gradle build process. The value can be set to either a jdk or jre location; however, using a JDK is safer depending on what your build does. This does not affect the version of Java used to launch the Gradle client VM.

You can also control the JVM used to run Gradle itself using the Daemon JVM criteria.

Default is derived from your environment (JAVA_HOME or the path to java) if the setting is unspecified.
org.gradle.java.installations.auto-detect=(true,false): When set to true, Gradle will automatically detect the JDK installations available on the system when locating Java toolchains. All JDK installation sources are additive, meaning if multiple sources are specified, Gradle will consider all sources when finding JDK installations.

Default is true.
org.gradle.java.installations.auto-download=(true,false): When set to true, Gradle will automatically download JDK installations when locating Java toolchains. All JDK installation sources are additive, meaning if multiple sources are specified, Gradle will consider all sources when finding JDK installations.

Default is true.
org.gradle.java.installations.paths=(list of JDK installations): When set, Gradle will use the specified JDK installation paths when locating Java toolchains. This setting is a comma-separated list of paths to directories where JDK installations are located. All JDK installation sources are additive, meaning if multiple sources are specified, Gradle will consider all sources when finding JDK installations.

Default is empty, meaning Gradle will not use any explicitly declared paths to find JDK installations.
org.gradle.java.installations.fromEnv=(list of environment variables): When set, Gradle will use the JDK installations specified in the listed environment variables when locating Java toolchains. This setting is a comma-separated list of environment variable names. All JDK installation sources are additive, meaning if multiple sources are specified, Gradle will consider all sources when finding JDK installations.

Default is empty, meaning Gradle will not use any environment variables to find JDK installations.
org.gradle.jvmargs=(JVM arguments): Specifies the JVM arguments used for the Gradle Daemon. The setting is particularly useful for configuring JVM memory settings for build performance. This does not affect the JVM settings for the Gradle client VM.

Default is -Xmx512m "-XX:MaxMetaspaceSize=384m".
org.gradle.logging.level=(quiet,warn,lifecycle,info,debug): When set to quiet, warn, info, or debug, Gradle will use this log level. The values are not case-sensitive.

Default is lifecycle level.
org.gradle.parallel=(true,false): When configured, Gradle will fork up to org.gradle.workers.max JVMs to execute projects in parallel.

Default is false.
org.gradle.priority=(low,normal): Specifies the scheduling priority for the Gradle daemon and all processes launched by it.

Default is normal.
org.gradle.projectcachedir=(directory): Specify the project-specific cache directory. Defaults to .gradle in the root project directory."

Default is .gradle.
org.gradle.problems.report=(true|false): Enable (true) or disable (false) the generation of build/reports/problems-report.html. true is the default. The report is generated with problems provided to the Problems API.
org.gradle.tooling.parallel=(true,false) Since 9.4.0: Allows running Tooling Model Builders in parallel, which can improve IDE Sync times. An explicit value will override org.gradle.parallel in this context.

Default is the value of org.gradle.parallel.
org.gradle.isolated-projects=(true,false) Since 9.7.0: Enables Isolated Projects, which configures projects in parallel and implies enabling the Configuration Cache.

Default is false.
org.gradle.isolated-projects.diagnostics=(true,false) Since 9.7.0: Enables Diagnostics mode for Isolated Projects, which runs project configuration sequentially to surface violations across all projects in a deterministic manner. Requires Isolated Projects to be enabled.

Default is false.
org.gradle.isolated-projects.dangerously-ignore-problems=(true,false) Since 9.7.0: Ignores Isolated Projects violations so that a parallel build or sync can be timed to estimate the speedup before violations are fixed. Violations are still reported but do not fail the build. Build outputs may be incorrect. Requires Isolated Projects to be enabled.

Default is false.
org.gradle.vfs.verbose=(true,false): Configures verbose logging when watching the file system.

Default is false.
org.gradle.vfs.watch=(true,false): Toggles watching the file system. When enabled, Gradle reuses information it collects about the file system between builds.

Default is true on operating systems where Gradle supports this feature.
org.gradle.warning.mode=(all,fail,summary,none): When set to all, summary, or none, Gradle will use different warning type display.

Default is summary.

org.gradle.workers.max=(max # of worker processes): When configured, Gradle will use a maximum of the given number of workers.

Default is the number of CPU processors.

Environment variables

Gradle provides a number of environment variables, which are listed below. Environment variables can be retrieved in build scripts lazily using providers.environmentVariable().

Setting environment variables

Let’s take an example that sets the $JAVA_HOME environment variable:

$ set JAVA_HOME=C:\Path\To\Your\Java\Home   // Windows
$ export JAVA_HOME=/path/to/your/java/home  // Mac/Linux

You can access environment variables as properties in the build script using the System.getenv() method:

task printEnvVariables {
    doLast {
        println "JAVA_HOME: ${System.getenv('JAVA_HOME')}"
    }
}

Environment variables reference

The following environment variables are available for the gradle command:

GRADLE_HOME

Installation directory for Gradle.

Can be used to specify a local Gradle version instead of using the wrapper.

You can add GRADLE_HOME/bin to your PATH for specific applications and use cases (such as testing an early release for Gradle).

JAVA_OPTS

Used to pass JVM options and custom settings to the JVM.

export JAVA_OPTS="-Xmx18928m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8 -Djava.awt.headless=true -Dkotlin.daemon.jvm.options=-Xmx6309m"

GRADLE_OPTS

Specifies JVM arguments to use when starting the Gradle client VM.

The client VM is lightweight and mainly handles command-line input and output, so it’s uncommon to change its VM options.

While GRADLE_OPTS typically doesn’t affect the daemon, you can use it to pass arguments to the daemon by setting the org.gradle.jvmargs system property. This is the recommended way to configure the daemon’s JVM options, such as heap size or memory settings, via an environment variable.

GRADLE_USER_HOME

Specifies the GRADLE_USER_HOME directory for Gradle to store its global configuration properties, initialization scripts, caches, log files and more.

Defaults to USER_HOME/.gradle if not set.

GRADLE_DAEMON_BIND_ADDRESS

Specifies the IP address or hostname that Gradle uses to bind the local socket for client-daemon and cross-daemon communication.

By default, Gradle automatically selects the loopback address (or wildcard address as a fallback) for this socket. This may not work correctly in environments with specific network configurations, such as multiple network interfaces, multiple TCP/IP stacks etc.

Setting this variable skips auto-detection and uses the provided address directly:

GRADLE_DAEMON_BIND_ADDRESS=192.168.1.10 ./gradlew build

JAVA_HOME

Specifies the JDK installation directory to use for the client VM.

This VM is also used for the daemon unless a different one is specified in a Gradle properties file with org.gradle.java.home or using the Daemon JVM criteria.

GRADLE_LIBS_REPO_OVERRIDE

Overrides for the default Gradle library repository.

Can be used to specify a default Gradle repository URL in org.gradle.plugins.ide.internal.resolver.

Useful override to specify an internally hosted repository if your company uses a firewall/proxy.

NO_COLOR

When present and non-empty, disables color output while preserving other styling (bold, underline) and rich features (progress bars, animations).

Follows the no-color.org convention. See Customizing log format for more options.

Build Lifecycle

The build lifecycle is the sequence of phases Gradle executes to turn your build scripts into completed work, from initializing the build environment to configuring projects and finally executing tasks.

Build Phases

A build has three distinct phases. Gradle runs these phases in order:

Phase 1. Initialization

Phase 2. Configuration

Phase 3. Execution

Detects projects and included builds

Configures projects and builds a task graph

Schedules and executes the selected tasks

Phase 1. Initialization

In the initialization phase, Gradle detects the set of projects (root and subprojects) and included builds participating in the build.

Gradle first runs any init scripts, then evaluates the settings file, settings.gradle(.kts), and instantiates a Settings object.

Then, Gradle instantiates Project object instances for each project included in the build (using includeBuild() or include() in the settings file).

Phase 2. Configuration

In the configuration phase, Gradle registers tasks and other properties to the projects found by the initialization phase.

Gradle evaluates the build files of every participating project, then constructs the task graph by analyzing the input and output dependencies of tasks.

Note

When the Configuration Cache is enabled, the configuration phase also includes a serialization sub-phase, where Gradle stores the task graph while simultaneously precomputing some of the task state and resolving dependencies. This is work that would otherwise be deferred to execution. See Configuration Cache - How It Works for more details.

Phase 3. Execution

In the execution phase, Gradle runs the selected tasks.

Gradle uses the task execution graph generated by the configuration phase to determine which tasks to execute and in what order.

Gradle can execute tasks that don’t depend on each other, in the same project, in parallel.

The Phases in Build Scripts

The following example shows which parts of settings and build files correspond to various build phases:

settings.gradle.kts

rootProject.name = "basic"
println("This is executed during the initialization phase.")

build.gradle.kts

// Configuration Phase
println("This is executed during the configuration phase.")

tasks.register("configured") {
    println("This is also executed during the configuration phase.")
}

// Execution Phase
tasks.register("test") {
    doLast {
        println("This is executed during the execution phase.")
    }
}

// Configurations AND Execution Phase
tasks.register("testBoth") {
    println("This is executed during the configuration phase as well.")
    doFirst {
        println("This is executed first during the execution phase.")
    }
    doLast {
        println("This is executed last during the execution phase.")
    }
}

settings.gradle

rootProject.name = 'basic'
println 'This is executed during the initialization phase.'

build.gradle

// Configuration Phase
println 'This is executed during the configuration phase.'

tasks.register('configured') {
    println 'This is also executed during the configuration phase.'
}

// Execution Phase
tasks.register('test') {
    doLast {
        println 'This is executed during the execution phase.'
    }
}

// Configurations AND Execution Phase
tasks.register('testBoth') {
    println 'This is executed during the configuration phase as well.'
    doFirst {
	  println 'This is executed first during the execution phase.'
	}
	doLast {
	  println 'This is executed last during the execution phase.'
	}
}

The following command executes the test and testBoth tasks specified above:

$ ./gradlew test testBoth

This is executed during the initialization phase.

> Configure project :
This is executed during the configuration phase.
This is executed during the configuration phase as well.

> Task :test
This is executed during the execution phase.

> Task :testBoth
This is executed first during the execution phase.
This is executed last during the execution phase.

BUILD SUCCESSFUL in 0s
2 actionable tasks: 2 executed

$ ./gradlew test testBoth

This is executed during the initialization phase.

> Configure project :
This is executed during the configuration phase.
This is executed during the configuration phase as well.

> Task :test
This is executed during the execution phase.

> Task :testBoth
This is executed first during the execution phase.
This is executed last during the execution phase.

BUILD SUCCESSFUL in 0s
2 actionable tasks: 2 executed

Because Gradle only configures requested tasks and their prerequisites, the configured task never configures.

Build Lifecycle Timeline

Understanding the precise sequence in which Gradle evaluates scripts and triggers hooks is the key to mastering build logic. This timeline provides a comprehensive overview of the Gradle build flow when the Configuration Cache and Isolated Projects are disabled:

Phase Seq. Hook / Block Location Purpose

Initialization

Init Scripts

~/.gradle/init.d/*.gradle

Global environment setup (e.g., enterprise repos).

gradle.beforeSettings

init script or settings.gradle(.kts)

Runs before the settings file is even parsed.

pluginManagement { … }

settings.gradle(.kts)

Must be first. Defines plugin repos and version rules.

plugins { … }

settings.gradle(.kts)

Applies plugins to the Settings object (e.g., Build Scans).

Settings Script Body

settings.gradle(.kts)

Evaluates include(":project") to define build structure.

gradle.settingsEvaluated

init script or settings.gradle(.kts)

Settings are fully processed; Project objects are created.

gradle.projectsLoaded

init script or settings.gradle(.kts)

All project instances exist but aren’t configured yet.

Configuration

gradle.lifecycle.beforeProject

init script or build.gradle(.kts)

Not recommended. Fires immediately before each project starts evaluating.

project.beforeEvaluate

init script or parent project’s build.gradle(.kts)

Runs before a specific project’s build script is evaluated.

buildscript { … }

build.gradle(.kts)

Sets the classpath for the build script itself.

plugins { … }

build.gradle(.kts)

Applies plugins and adds DSL/Tasks.

Build Script Body

build.gradle(.kts)

Registers tasks (tasks.register) and configures properties.

project.afterEvaluate

build.gradle(.kts)

Not recommended. Runs after a specific project is evaluated; useful for reacting to another project’s configuration.

gradle.lifecycle.afterProject

init script or root build.gradle(.kts)

Fires immediately after each project finishes evaluating.

gradle.projectsEvaluated

init script or root build.gradle(.kts)

All project scripts have run; final chance to tweak the graph.

Task Graph Construction

Internal (TaskExecutionGraph, TaskExecutionGraphListener, TaskExecutionListener)

Gradle calculates the DAG based on requested tasks.

Execution

17a

Task Input Snapshotting

Internal (onlyIf{}, upToDateWhen{})

Evaluated per task to determine whether it should be skipped or executed.

17b

Dependency Graph Resolution*

Internal (ResolutionResult, ResolvedComponentResult, ResolvedVariantResult)

Constructs a dependency graph based on declared dependencies.

17c

Artifact Resolution*

Internal (ArtifactCollection, ResolvedArtifact)

Dependencies are downloaded from repositories.

Task Execution

Console / CLI (@TaskAction,doFirst{},doLast{})

Tasks run.

* Dependency Graph Resolution and Artifact Resolution are normally deferred until the Execution Phase. However, any build logic that eagerly accesses a configuration’s resolved state, such as calling configuration.files, configuration.resolvedConfiguration, or iterating a configuration directly, will trigger resolution immediately at that point in the build lifecycle.

Important

When the Configuration Cache is enabled, Dependency Graph Resolution and Artifact Resolution must be completed during the Configuration Phase rather than at execution time, since they are required to fully describe the task graph before the result can be serialized. You can refer to Configuration Cache - How It Works to learn more.

Task Graphs

For example, if your project includes tasks such as build, assemble, and createDocs, and you declare that assemble depends on build, and createDocs depends on assemble, Gradle constructs a graph with this order: build → assemble → createDocs.

Gradle builds the task graph before executing any task(s).

Across all projects in the build, tasks form a Directed Acyclic Graph (DAG).

This diagram shows two example task graphs, one abstract and the other concrete, with dependencies between tasks represented as arrows:

Hooks into the Gradle Build Lifecycle

Gradle exposes several APIs that let you listen to or react to key points in the build lifecycle.

Some APIs let you hook into those phases in init scripts, settings.gradle(.kts) or build.gradle(.kts) to customize or inspect the build as Gradle configures it. These hooks let you:

react to the structure of the build (root + subprojects),
configure all projects before their own build scripts are evaluated,
debug or collect information during configuration.

Lifecycle API

The GradleLifecycle API, accessible through the gradle object, can be used to register actions to be executed at certain points in the build lifecycle:

buildStarted -> DEPRECATED in Gradle 6
 └─ beforeSettings
     └── settingsEvaluated
          └── projectsLoaded
               ├── beforeProject
               ├── afterProject
               └── projectsEvaluated
                     └── buildFinished -> DEPRECATED in Gradle 7

Here is a quick overview:

# Hook Best for

gradle.beforeSettings

Early wiring from an init script: global logging/metrics, tweaking gradle.startParameter, choosing different settings files, or setting values on the Settings object before it’s evaluated.

gradle.settingsEvaluated

Adjusting repositories, enabling build scans, reading environment variables, or changing build layout.

gradle.projectsLoaded

Applying configuration to every project (for example, adding a plugin to all subprojects).

gradle.lifecycle.beforeProject

Applying defaults, logging project configuration start.

gradle.lifecycle.afterProject

Validating configuration or detecting missing plugins.

gradle.projectsEvaluated

Performing cross-project validation, configuration summaries, or creating aggregated tasks.

`beforeSettings`

Where: init script.
When: By the time settings.gradle(.kts) is executing, beforeSettings has already fired.

callbacks.init.gradle.kts

// 1. beforeSettings: tweak start parameters / log early info
// before the build settings have been loaded and evaluated.
gradle.beforeSettings {
    println("[beforeSettings] gradleUserHome = ${gradle.gradleUserHomeDir}")

    // Example: default to --parallel if an env var is set
    if (System.getenv("CI") == "true") {
        println("[beforeSettings] Enabling parallel execution on CI")
        gradle.startParameter.isParallelProjectExecutionEnabled = true
    } else {
        println("[beforeSettings] Disabling parallel execution, not on CI")
        gradle.startParameter.isParallelProjectExecutionEnabled = false
    }
}

callbacks.init.gradle

// 1. beforeSettings: tweak start parameters / log early info
// before the build settings have been loaded and evaluated.
gradle.beforeSettings {
    println("[beforeSettings] gradleUserHome = ${gradle.gradleUserHomeDir}")

    // Example: default to --parallel if an env var is set
    if (System.getenv("CI") == "true") {
        println("[beforeSettings] Enabling parallel execution on CI")
        gradle.startParameter.parallelProjectExecutionEnabled = true
    } else {
        println("[beforeSettings] Disabling parallel execution, not on CI")
        gradle.startParameter.parallelProjectExecutionEnabled = false
    }

    println("")
}

`settingsEvaluated`

Where: settings.gradle(.kts).
When: After the settings file finishes evaluating.

callbacks.init.gradle.kts

// 2. settingsEvaluated: adjust build layout / repositories / scan config
// when the build settings have been loaded and evaluated.
gradle.settingsEvaluated {
    println("[settingsEvaluated] rootProject = ${rootProject.name}")

    // Example: enforce a company-wide pluginManagement repo
    pluginManagement.repositories.apply {
        println("[settingsEvaluated] Ensuring company plugin repo is configured")
        mavenCentral()
    }
}

callbacks.init.gradle

// 2. settingsEvaluated: adjust build layout / repositories / scan config
// when the build settings have been loaded and evaluated.
gradle.settingsEvaluated { settings ->
    println("[settingsEvaluated] rootProject = ${settings.rootProject.name}")

    // Example: enforce a company-wide pluginManagement repo
    settings.pluginManagement.repositories.with {
        println("[settingsEvaluated] Ensuring company plugin repo is configured")
        mavenCentral()
    }

    println("")
}

`projectsLoaded`

Where: settings.gradle(.kts).
When: All projects have been discovered but not yet configured.

callbacks.init.gradle.kts

// 3. projectsLoaded: we know the full project graph, but nothing configured yet
// to be called when the projects for the build have been created from the settings.
gradle.projectsLoaded {
    println("[projectsLoaded] Projects discovered: " + rootProject.allprojects.joinToString { it.name })

    // Example: Add a custom property (using the extra properties extension)
    allprojects {
        println("[projectsLoaded] Setting extra property on ${name}")
        extensions.extraProperties["isInitScriptConfigured"] = true
    }
}

callbacks.init.gradle

// 3. projectsLoaded: we know the full project graph, but nothing configured yet
// to be called when the projects for the build have been created from the settings.
gradle.projectsLoaded {
    println "[projectsLoaded] Projects discovered: " + rootProject.allprojects.collect { it.name }.join(', ')

    // Example: Add a custom property (using the extra properties extension)
    allprojects {
        println("[projectsLoaded] Setting extra property on ${name}")
        extensions.extraProperties["isInitScriptConfigured"] = true
    }
}

`beforeProject`

Where: build.gradle(.kts) or anywhere you have access to the Gradle instance.
When: For each project as its build script is evaluated.

callbacks.init.gradle.kts

// to be called immediately before a project is evaluated.
gradle.lifecycle.beforeProject {
    println("[lifecycle.beforeProject] Started configuring ${path}")
}

// 4. beforeProject: runs before each build.gradle(.kts) is evaluated
// to be called immediately before a project is evaluated.
gradle.beforeProject {
    println("[beforeProject] Started configuring ${path}")

    println("[beforeProject] Setup a global build directory for ${name}")
    layout.buildDirectory.set(
        layout.projectDirectory.dir("build")
    )
}

callbacks.init.gradle

// to be called immediately before a project is evaluated.
gradle.lifecycle.beforeProject {
    println("[lifecycle.beforeProject] Started configuring ${path}")
}

// 4. beforeProject: runs before each build.gradle(.kts) is evaluated
// to be called immediately before a project is evaluated.
gradle.beforeProject { project ->
    println("[beforeProject] Started configuring ${project.path}")

    println("[beforeProject] Setup a global build directory for ${project.name}")
    project.layout.buildDirectory.set(
        project.layout.projectDirectory.dir("build")
    )
}

Tip	When Isolated Projects is enabled, applying a plugin that is resolved lazily — for example a convention plugin from a build registered via `pluginManagement.includeBuild(…)`, or a third-party plugin from a repository — requires additional setup. See Applying plugins from a lifecycle callback.

`afterProject`

Where: build.gradle(.kts) or anywhere you have access to the Gradle instance.
When: For each project as its build script is evaluated.

callbacks.init.gradle.kts

// 5. afterProject: runs after each build.gradle(.kts) is evaluated
// to be called immediately after a project is evaluated.
gradle.afterProject {
    println("[afterProject] Finished configuring ${path}")

    // Example: apply the Java plugin to all projects that don’t have any plugin yet
    if (plugins.hasPlugin("java")) {
        println("[afterProject] ${path} already has the java plugin")
    } else {
        println("[afterProject] Applying java plugin to ${path}")
        apply(plugin = "java")
    }
}

// to be called immediately after a project is evaluated.
gradle.lifecycle.afterProject {
    println("[lifecycle.afterProject] Finished configuring ${path}")
}

callbacks.init.gradle

// 5. afterProject: runs after each build.gradle(.kts) is evaluated
// to be called immediately after a project is evaluated.
gradle.afterProject { project ->
    println("[afterProject] Finished configuring ${project.path}")

    // Example: apply the Java plugin to all projects that don’t have any plugin yet
    if (project.plugins.hasPlugin("java")) {
        println("[afterProject] ${project.path} already has the java plugin")
    } else {
        println("[afterProject] Applying java plugin to ${project.path}")
        project.apply(plugin: "java")
    }
}

// to be called immediately after a project is evaluated.
gradle.lifecycle.afterProject {
    println("[lifecycle.afterProject] Finished configuring ${path}")
}

Tip	When Isolated Projects is enabled, applying a plugin that is resolved lazily — for example a convention plugin from a build registered via `pluginManagement.includeBuild(…)`, or a third-party plugin from a repository — requires additional setup. See Applying plugins from a lifecycle callback.

`projectsEvaluated`

Where: build.gradle(.kts) or anywhere you have access to the Gradle instance.
When: After all projects have been evaluated (i.e., all build.gradle(.kts) files are read and configuration is complete), but before task graph is finalized and before execution starts.

callbacks.init.gradle.kts

// 6. projectsEvaluated: all projects are fully configured, safe for cross-project checks
// to be called when all projects for the build have been evaluated.
gradle.projectsEvaluated {
    println("[projectsEvaluated] All projects evaluated")

    // Example: globally configure the java plugin
    allprojects {
        extensions.findByType<JavaPluginExtension>()?.let { javaExtension ->
            if (javaExtension.toolchain.languageVersion.isPresent) {
                println("[projectsEvaluated] ${path} uses Java plugin with toolchain ${javaExtension.toolchain.displayName}")
            } else {
                println("[projectsEvaluated] WARNING: ${path} uses Java plugin but no toolchain is configured, setting Java 17")
                javaExtension.toolchain.languageVersion.set(JavaLanguageVersion.of(17))
            }
        }
    }
}

callbacks.init.gradle

// 6. projectsEvaluated: all projects are fully configured, safe for cross-project checks
// to be called when all projects for the build have been evaluated.
gradle.projectsEvaluated {
    println("[projectsEvaluated] All projects evaluated")

    // Example: globally configure the java plugin
    allprojects { project ->
        def javaExtension = project.extensions.findByType(JavaPluginExtension)
        if(javaExtension) {
            if (javaExtension.toolchain.languageVersion.orNull != null) {
                println("[projectsEvaluated] ${path} uses Java plugin with toolchain ${javaExtension.toolchain.displayName}")
            } else {
                println("[projectsEvaluated] WARNING: ${path} uses Java plugin but no toolchain is configured, setting Java 17")
                javaExtension.toolchain.languageVersion.set(JavaLanguageVersion.of(17))
            }
        }
    }
}

Build Listeners

Listeners are interfaces you implement to react to build lifecycle events.

Many BuildListeners are deprecated and/or are not Configuration Cache friendly, use them with caution:

Interface What it observes Works with CC?

BuildListener

Fires when projects are loaded/evaluated.

❌

ProgressListener

Fires when the execution of an operation progresses.

✅

(Partially Deprecated) TaskActionListener

Fires when a task has started or completed its action.

❌

(Deprecated) TaskExecutionListener

Fires before and after each task executes.

❌

(Deprecated) TaskExecutionGraphListener

Fires when the task execution graph has been populated.

❌

OperationCompletionListener

Fires when an operation completes.

✅

DependencyResolutionListener

Fires before and after dependency resolution.

❌

ProjectEvaluationListener

Fires before and after each project is evaluated.

❌

TestListener

Fires at different times during test execution.

❌

You implement a listener interface and typically register it on the gradle object. The TaskExecutionGraphListener fires once after the task graph has been calculated, but before any task executes.

This example uses graph.allTasks to inspect what Gradle plans to run, and graph.hasTask() to conditionally adjust behaviour:

build.gradle.kts

gradle.taskGraph.addTaskExecutionGraphListener { graph ->
    val tasks = graph.allTasks.joinToString("\n  ") { it.path }
    println("[TaskExecutionGraphListener] Graph is ready. Tasks to execute:\n  $tasks")

    if (graph.hasTask(":skippedTask")) {
        println("[TaskExecutionGraphListener] :skippedTask is in the graph (it will still be skipped via onlyIf)")
    }
}

tasks.register("hello") {
    group = "demo"
    description = "Prints a greeting. Always runs — observe TaskExecutionListener output."
    doLast {
        println("Hello from the :hello task!")
    }
}

tasks.register("upToDateTask") {
    group = "demo"
    description = "Writes a file. Runs once, then reports UP-TO-DATE on subsequent runs."

    val outputFile = layout.buildDirectory.file("up-to-date-output.txt")
    outputs.file(outputFile)

    doLast {
        outputFile.get().asFile.writeText("generated")
        println("upToDateTask: file written.")
    }
}

tasks.register("skippedTask") {
    group = "demo"
    description = "Always skipped via onlyIf — observe SKIPPED in TaskExecutionListener."
    onlyIf { false }
    doLast {
        println("This never prints.")
    }
}

build.gradle

gradle.taskGraph.addTaskExecutionGraphListener { graph ->
    def tasks = graph.allTasks.collect { it.path }.join("\n  ")
    println("[TaskExecutionGraphListener] Graph is ready. Tasks to execute:\n  ${tasks}")

    if (graph.hasTask(":skippedTask")) {
        println("[TaskExecutionGraphListener] :skippedTask is in the graph (it will still be skipped via onlyIf)")
    }
}

tasks.register("hello") {
    group = "demo"
    description = "Prints a greeting. Always runs."
    doLast {
        println("Hello from the :hello task!")
    }
}

tasks.register("upToDateTask") {
    group = "demo"
    description = "Writes a file. Runs once, then reports UP-TO-DATE on subsequent runs."

    def outputFile = layout.buildDirectory.file("up-to-date-output.txt")
    outputs.file(outputFile)

    doLast {
        outputFile.get().asFile.text = "generated"
        println("upToDateTask: file written.")
    }
}

tasks.register("skippedTask") {
    group = "demo"
    description = "Always skipped via onlyIf."
    onlyIf { false }
    doLast {
        println("This never prints.")
    }
}

Note that tasks skipped via onlyIf still appear in the graph; skipping is evaluated later, per task, during execution:

[TaskExecutionGraphListener] Graph is ready. Tasks to execute:
  :hello
  :skippedTask
  :upToDateTask
  :runAll
[TaskExecutionGraphListener] :skippedTask is in the graph (it will still be skipped via onlyIf)

> Task :hello
Hello from the :hello task!

> Task :skippedTask SKIPPED

> Task :upToDateTask
upToDateTask: file written.

> Task :runAll

BUILD SUCCESSFUL in 0s
2 actionable tasks: 2 executed

Build Services

Build Services are used to share state or resources across tasks and across the build lifecycle.

This example implements OperationCompletionListener directly on the service to count tasks as they complete, and uses close() as an end-of-build hook to print the final summary, whether the build succeeded or failed:

build.gradle.kts

abstract class BuildDurationService
    : BuildService<BuildServiceParameters.None>, AutoCloseable {

    private val startTime = System.currentTimeMillis()

    // Called once at the end of the build — reliable teardown hook
    override fun close() {
        val elapsed = System.currentTimeMillis() - startTime
        println("─────────────────────────────────────")
        println("  Build duration : ${elapsed}ms")
        println("─────────────────────────────────────")
    }
}

val buildDurationService = gradle.sharedServices.registerIfAbsent("buildDuration", BuildDurationService::class) {
    maxParallelUsages = 1
}

tasks.register("taskA") {
    group = "demo"
    usesService(buildDurationService)
    val service = buildDurationService
    doLast {
        service.get()
        println("taskA running...")
        Thread.sleep(200)
    }
}

tasks.register("taskB") {
    group = "demo"
    doLast {
        println("taskB running...")
        Thread.sleep(300)
    }
}

build.gradle

abstract class BuildDurationService
    implements BuildService<BuildServiceParameters.None>, AutoCloseable {

    private final long startTime = System.currentTimeMillis()

    // Called once at the end of the build — reliable teardown hook
    @Override
    void close() {
        def elapsed = System.currentTimeMillis() - startTime
        println("─────────────────────────────────────")
        println("  Build duration : ${elapsed}ms")
        println("─────────────────────────────────────")
    }
}

def buildDurationService = gradle.sharedServices.registerIfAbsent("buildDuration", BuildDurationService) {
    maxParallelUsages = 1
}

tasks.register("taskA") {
    group = "demo"
    usesService(buildDurationService)
    def service = buildDurationService
    doLast {
        service.get()
        println("taskA running...")
        Thread.sleep(200)
    }
}

tasks.register("taskB") {
    group = "demo"
    doLast {
        println("taskB running...")
        Thread.sleep(300)
    }
}

The hooks are used to calculate the duration of the build:

> Task :taskA
taskA running...

> Task :taskB
taskB running...

> Task :runAll
─────────────────────────────────────
  Build duration : 510ms
─────────────────────────────────────

BUILD SUCCESSFUL in 0s
2 actionable tasks: 2 executed

Flow Actions Incubating

FlowAction is a newer API (introduced in Gradle 7.6) that lets you run logic in response to build lifecycle events, most commonly, when the build finishes. It was introduced as a Configuration Cache and Isolated Projects compatible alternative to BuildListener and other deprecated lifecycle listeners.

To use a Flow Action, you define a class implementing FlowAction<T> and a matching Parameters interface that declares the inputs your action needs. You then register it inside a Plugin using FlowScope, which is injected by Gradle alongside FlowProviders:

build.gradle.kts

abstract class PrintBuildResultPlugin : Plugin<Project> {

    @get:Inject
    abstract val flowScope: FlowScope

    @get:Inject
    abstract val flowProviders: FlowProviders

    override fun apply(target: Project) {
        flowScope.always(BuildResultPrinter::class.java) {
            parameters.buildResult.set(flowProviders.buildWorkResult)
        }
    }
}

abstract class BuildResultPrinter : FlowAction<BuildResultPrinter.Parameters> {

    interface Parameters : FlowParameters {
        @get:Input
        val buildResult: Property<BuildWorkResult>
    }

    override fun execute(parameters: Parameters) {
        val result = parameters.buildResult.get()
        if (result.failure.isPresent) {
            println("Build failed: ${result.failure.get().message}")
        } else {
            println("Build succeeded")
        }
    }
}

build.gradle

abstract class PrintBuildResultPlugin implements Plugin<Project> {

    @Inject
    abstract FlowScope getFlowScope()

    @Inject
    abstract FlowProviders getFlowProviders()

    @Override
    void apply(Project target) {
        flowScope.always(BuildResultPrinter) {
            parameters.buildResult.set(flowProviders.buildWorkResult)
        }
    }
}

abstract class BuildResultPrinter implements FlowAction<BuildResultPrinter.Parameters> {

    interface Parameters extends FlowParameters {
        @Input
        Property<BuildWorkResult> getBuildResult()
    }

    @Override
    void execute(Parameters parameters) {
        def result = parameters.buildResult.get()
        if (result.failure.isPresent()) {
            println "Build failed: ${result.failure.get().message}"
        } else {
            println "Build succeeded"
        }
    }
}

As expected, we see the build finish success message:

Build succeeded

BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed

Build Scan

Gradle provides multiple ways to inspect your build:

Profile with a Build Scan
Local profile reports
Low level profiling

What is a Build Scan?

A Build Scan is a persistent, shareable record of what happened when running a build. They provide detailed insights you can use to diagnose performance issues, identify build failures, and share context with your team.

A Build Scan is created locally but published to a secure external server managed by Gradle. They do not run code on your machine, and they never modify your build. You can choose whether to publish a scan, and each scan is assigned a unique (private-by-default) URL.

Note	For information on what data is collected and how it’s handled, see the Gradle.com Privacy Policy.

In Gradle 4.3 and above, you can create a Build Scan using the --scan command line option:

$ ./gradlew build --scan

For older Gradle versions, the Develocity Plugin User Manual explains how to generate a Build Scan.

At the end of your build, Gradle displays a URL where you can find your Build Scan:

BUILD SUCCESSFUL in 2s
4 actionable tasks: 4 executed

Publishing Build Scan...
https://gradle.com/s/e6ircx2wjbf7e

This section explains how to profile your build with a Build Scan.

1. Profile with a Build Scan

The performance page can help use a Build Scan to profile a build. To get there, click "Performance" in the left hand navigation menu or follow the "Explore performance" link on the Build Scan home page:

Figure 1. Performance page link on Build Scan home page

The performance page shows how long it took to complete different stages of a build. This page shows how long it took to:

start up
configure the build’s projects
resolve dependencies
execute tasks

You also get details about environmental properties, such as whether a daemon was used or not.

Figure 2. Build Scan performance page

In the above Build Scan, configuration takes over 13 seconds. Click on the "Configuration" tab to break this stage into component parts, exposing the cause of the slowness.

Figure 3. Build Scan configuration breakdown

Here you can see the scripts and plugins applied to the project in descending order of how long they took to apply. The slowest plugin and script applications are good candidates for optimization. For example, the script script-b.gradle was applied once but took 3 seconds. Expand that row to see where the build applied this script.

Figure 4. Showing the application of script-b.gradle to the build

You can see that subproject :app1 applied the script once, from inside of that subproject’s build.gradle file.

2. Profile report

If you prefer not to use a Build Scan, you can generate an HTML report in the build/reports/profile directory of your root project. To generate this report, use the --profile command-line option:

$ ./gradlew --profile <tasks>

Each profile report has a timestamp in its name to avoid overwriting existing ones.

The report displays a breakdown of the time taken to run the build. However, this breakdown is not as detailed as a Build Scan. The following profile report shows the different categories available:

Figure 5. An example profile report

3. Low level profiling

Sometimes your build can be slow even though your build scripts do everything right. This often comes down to inefficiencies in plugins and custom tasks or constrained resources. Use the Gradle Profiler to find these kinds of bottlenecks. With the Gradle Profiler, you can define scenarios like "Running 'assemble' after making an ABI-breaking change" and run your build several times to collect profiling data. Use the Profiler to produce a Build Scan. Or combine it with method profilers like JProfiler and YourKit. These profilers can help you find inefficient algorithms in custom plugins. If you find that something in Gradle itself slows down your build, don’t hesitate to send a profiler snapshot to performance@gradle.com.

Performance categories

Both a Build Scan and local profile reports break down build execution into the same categories. The following sections explain those categories.

Startup

This reflects Gradle’s initialization time, which consists mostly of:

JVM initialization and class loading
Downloading the Gradle distribution if you’re using the wrapper
Starting the daemon if a suitable one isn’t already running
Executing Gradle initialization scripts

Even when a build execution has a long startup time, subsequent runs usually see a dramatic drop off in startup time. Persistently slow build startup times are usually the result of problems in your init scripts. Double check that the work you’re doing there is necessary and performant.

Settings and buildSrc

After startup, Gradle initializes your project. Usually, Gradle only processes your settings file. If you have custom build logic in a buildSrc directory, Gradle also processes that logic. After building buildSrc once, Gradle considers it up to date. The up-to-date checks take significantly less time than logic processing. If your buildSrc phase takes too much time, consider breaking it out into a separate project. You can then add that project’s JAR artifact as a dependency.

The settings file rarely contains code with significant I/O or computation. If you find that Gradle takes a long time to process it, use more traditional profiling methods, like the Gradle Profiler, to determine the cause.

Loading projects

It normally doesn’t take a significant amount of time to load projects, nor do you have any control over it. The time spent here is basically a function of the number of projects you have in your build.

Continuous Builds

Continuous Build allows you to automatically re-execute the requested tasks when file inputs change. You can execute the build in this mode using the -t or --continuous command-line option.

For example, you can continuously run the test task and all dependent tasks by running:

$ ./gradlew test --continuous

Gradle will behave as if you ran gradle test after a change to sources or tests that contribute to the requested tasks. This means unrelated changes (such as changes to build scripts) will not trigger a rebuild. To incorporate build logic changes, the continuous build must be restarted manually.

Continuous build uses file system watching to detect changes to the inputs. If file system watching does not work on your system, then continuous build won’t work either. In particular, continuous build does not work when using --no-daemon.

When Gradle detects a change to the inputs, it will not trigger the build immediately. Instead, it will wait until no additional changes are detected for a certain period of time - the quiet period. You can configure the quiet period in milliseconds by the Gradle property org.gradle.continuous.quietperiod.

Terminating Continuous Build

If Gradle is attached to an interactive input source, such as a terminal, the continuous build can be exited by pressing CTRL-D (On Microsoft Windows, it is required to also press ENTER or RETURN after CTRL-D).

If Gradle is not attached to an interactive input source (e.g. is running as part of a script), the build process must be terminated (e.g. using the kill command or similar).

If the build is being executed via the Tooling API, the build can be cancelled using the Tooling API’s cancellation mechanism.

Limitations

Under some circumstances, continuous build may not detect changes to inputs.

Creating input directories

Sometimes, creating an input directory that was previously missing does not trigger a build, due to the way file system watching works. For example, creating the src/main/java directory may not trigger a build. Similarly, if the input is a filtered file tree and no files are matching the filter, the creation of matching files may not trigger a build.

Inputs of untracked tasks

Changes to the inputs of untracked tasks or tasks that have no outputs may not trigger a build.

Changes to files outside of project directories

Gradle only watches for changes to files inside the project directory. Changes to files outside the project directory will go undetected and not trigger a build.

Build cycles

Gradle starts watching for changes just before a task executes. If a task modifies its own inputs while executing, Gradle will detect the change and trigger a new build. If every time the task executes, the inputs are modified again, the build will be triggered again. This isn’t unique to continuous build. A task that modifies its own inputs will never be considered up-to-date when run "normally" without continuous build.

If your build enters a build cycle like this, you can track down the task by looking at the list of files reported changed by Gradle. After identifying the file(s) that are changed during each build, you should look for a task that has that file as an input. In some cases, it may be obvious (e.g., a Java file is compiled with compileJava). In other cases, you can use --info logging to find the task that is out-of-date due to the identified files.

Changes to symbolic links

In general, Gradle will not detect changes to symbolic links or to files referenced via symbolic links.

Changes to build logic are not considered

The current implementation does not recalculate the build model on subsequent builds. This means that changes to task configuration, or any other change to the build model, are effectively ignored.

Continuous Build in IDEs

Most modern IDEs like IntelliJ IDEA, Android Studio, or Eclipse already offer their own form of continuous compilation and test execution.

For example, If you’re only interested in triggering something on file changes (e.g., running tests or generating docs), you might consider using IntelliJ’s File Watchers feature as an alternative for specific tasks.

Gradle’s --continuous mode is designed for command-line use and is not typically integrated into IDE workflows. To use continuous build in an IDE environment, run ./gradlew <task> --continuous from a terminal window alongside the IDE.

File System Watching

Gradle maintains a Virtual File System (VFS) to calculate what needs to be rebuilt on repeat builds of a project. By watching the file system, Gradle keeps the VFS current between builds.

Enable

Gradle enables file system watching by default for supported operating systems since Gradle 7.

Run the build with the '--watch-fs' flag to force file system watching for a build.

To force file system watching for all builds (unless disabled with --no-watch-fs), add the following value to gradle.properties:

org.gradle.vfs.watch=true

Disable

To disable file system watching:

use the --no-watch-fs flag
set org.gradle.vfs.watch=false in gradle.properties

Excluding files and directories

Gradle automatically excludes some common directories (like .git, .gradle, and build/) from file system watching.

Locations managed by Gradle are never watched, because Gradle is their only writer and keeps the virtual file system up to date directly. This includes Gradle’s global caches and the project cache directory — the .gradle directory in the root project, or a custom location configured with --project-cache-dir. Because the project cache directory is not watched, it can be placed on any file system, including one that does not support watching, without affecting file system watching.

There is no public mechanism to configure additional file system watch excludes.

To reduce unnecessary watching and re-execution, consider limiting the inputs of specific tasks using fileTree.exclude().

Supported Operating Systems

Gradle uses native operating system features to watch the file system. Gradle supports file system watching on the following operating systems:

Windows 10, version 1709 and later
Linux, tested on the following distributions:
- Ubuntu 16.04
- CentOS Stream 9
- Red Hat Enterprise Linux (RHEL) 8
- Amazon Linux 2
- Alpine Linux 3.20
macOS 12 (Monterey) or later on Intel and ARM architectures

Supported File Systems

File system watching supports the following file system types:

APFS
btrfs
ext3
ext4
XFS
HFS+
NTFS

Gradle also supports VirtualBox’s shared folders.

Network file systems like Samba and NFS are not supported. Microsoft Dev Drives (ReFS) are also not supported.

Unsupported File Systems

When enabled by default, file system watching acts conservatively when it encounters content on unsupported file systems. This can happen if you mount a project directory or subdirectory from a network drive. Gradle doesn’t retain information about unsupported file systems between builds when enabled by default. If you explicitly enable file system watching, Gradle retains information about unsupported file systems between builds.

To verify that the operating system actually delivers events for a watched directory, Gradle writes a small probe file (file-system.probe). This probe is always created in the .gradle directory under the build root. The probe is removed when the build finishes.

Symlinks

Files and directories in your project that are accessed via symlinks do not benefit from file system-watching optimizations.

Logging

To view information about Virtual File System (VFS) changes at the beginning and end of a build, enable verbose VFS logging.

Set the org.gradle.vfs.verbose Daemon option to true to enable verbose logging.

You can do this on the command line with the following command:

$ gradle <task> -Dorg.gradle.vfs.verbose=true

Or configure the property in the gradle.properties file in the project root or your Gradle User Home:

org.gradle.vfs.verbose=true

This produces the following output at the start and end of the build:

$ ./gradlew assemble --watch-fs -Dorg.gradle.vfs.verbose=true

Received 3 file system events since last build while watching 1 locations
Virtual file system retained information about 2 files, 2 directories and 0 missing files since last build
> Task :compileJava NO-SOURCE
> Task :processResources NO-SOURCE
> Task :classes UP-TO-DATE
> Task :jar UP-TO-DATE
> Task :assemble UP-TO-DATE

BUILD SUCCESSFUL in 58ms
1 actionable task: 1 up-to-date
Received 5 file system events during the current build while watching 1 locations
Virtual file system retains information about 3 files, 2 directories and 2 missing files until next build

On Windows and macOS, Gradle might report changes received since the last build, even if you haven’t changed anything. These are harmless notifications about changes to Gradle’s caches and can be safely ignored.

Troubleshooting

Gradle does not detect some changes

Please let us know on the Gradle community Slack. If a build declares its inputs and outputs correctly, this should not happen. So it’s either a bug we must fix or your build lacks declaration for some inputs or outputs.

VFS state dropped due to lost state

Did you receive a message that reads Dropped VFS state due to lost state during a build? Please let us know on the Gradle community Slack. This means that your build cannot benefit from file system watching for one of the following reasons:

the Daemon received an unknown file system event
too many changes happened, and the watching API couldn’t handle it

Too many open files on macOS

If you receive the java.io.IOException: Too many open files error on macOS, raise your open files limit. See this post for more details.

Adjust inotify watches limit on Linux

File system watching uses inotify on Linux. Depending on the size of your build, it may be necessary to increase inotify limits. If you are using an IDE, then you probably already had to increase the limits in the past.

File system watching uses one inotify watch per watched directory. You can see the current limit of inotify watches per user by running:

cat /proc/sys/fs/inotify/max_user_watches

To increase the limit to e.g. 512K watches run the following:

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf

sudo sysctl -p --system

Each used inotify watch takes up to 1KB of memory. Assuming inotify uses all the 512K watches then file system watching could use up to 500MB. In a memory-constrained environment, you may want to disable file system watching.

Inspect inotify instances limit on Linux

File system watching initializes one inotify instance per daemon. You can see the current limit of inotify instances per user by running:

cat /proc/sys/fs/inotify/max_user_instances

The default per-user instances limit should be high enough, so we don’t recommend increasing that value manually.

DSLS AND APIS

Groovy

A Groovy Build Script Primer

Ideally, a Groovy build script looks mostly like configuration: setting some properties of the project, configuring dependencies, declaring tasks, and so on. That configuration is based on Groovy language constructs. This primer aims to explain what those constructs are and — most importantly — how they relate to Gradle’s API documentation.

The `Project` object

As Groovy is an object-oriented language based on Java, its properties and methods apply to objects. In some cases, the object is implicit — particularly at the top level of a build script, i.e. not nested inside a {} block.

Consider this fragment of build script, which contains an unqualified property and block:

version = '1.0.0.GA'

configurations {
    ...
}

Both version and configurations {} are part of org.gradle.api.Project.

This example reflects how every Groovy build script is backed by an implicit instance of Project. If you see an unqualified element and you don’t know where it’s defined, always check the Project API documentation to see if that’s where it’s coming from.

Caution

Avoid using Groovy MetaClass programming techniques in your build scripts. Gradle provides its own API for adding dynamic runtime properties.

Use of Groovy-specific metaprogramming can cause builds to retain large amounts of memory between builds that will eventually cause the Gradle daemon to run out-of-memory.

Properties

<obj>.<name>                // Get a property value
<obj>.<name> = <value>      // Set a property to a new value
"$<name>"                   // Embed a property value in a string
"${<obj>.<name>}"           // Same as previous (embedded value)

Examples

version = '1.0.1'
myCopyTask.description = 'Copies some files'

file("$projectDir/src")
println "Destination: ${myCopyTask.destinationDir}"

A property represents some state of an object. The presence of an = sign is a clear indicator that you’re looking at a property. Otherwise, a qualified name — it begins with <obj>. — without any other decoration is also a property.

If the name is unqualified, then it may be one of the following:

A task instance with that name.
A property on Project.
An extra property defined elsewhere in the project.
A property of an implicit object within a block.
A local variable defined earlier in the build script.

Note that plugins can add their own properties to the Project object. The API documentation lists all the properties added by core plugins. If you’re struggling to find where a property comes from, check the documentation for the plugins that the build uses.

Tip	When referencing a project property in your build script that is added by a non-core plugin, consider prefixing it with `project.` — it’s clear then that the property belongs to the project object.

Properties in the API documentation

The Groovy DSL reference shows properties as they are used in your build scripts, but the Javadocs only display methods. That’s because properties are implemented as methods behind the scenes:

A property can be read if there is a method named get<PropertyName> with zero arguments that returns the same type as the property.
A property can be modified if there is a method named set<PropertyName> with one argument that has the same type as the property and a return type of void.

Note that property names usually start with a lower-case letter, but that letter is upper case in the method names. So the getter method getProjectVersion() corresponds to the property projectVersion. This convention does not apply when the name begins with at least two upper-case letters, in which case there is not change in case. For example, getRAM() corresponds to the property RAM.

Examples

project.getVersion()
project.version

project.setVersion('1.0.1')
project.version = '1.0.1'

Methods

<obj>.<name>()              // Method call with no arguments
<obj>.<name>(<arg>, <arg>)  // Method call with multiple arguments
<obj>.<name> <arg>, <arg>   // Method call with multiple args (no parentheses)

Examples

myCopyTask.include '**/*.xml', '**/*.properties'

ext.resourceSpec = copySpec()   // `copySpec()` comes from `Project`

file('src/main/java')
println 'Hello, World!'

A method represents some behavior of an object, although Gradle often uses methods to configure the state of objects as well. Methods are identifiable by their arguments or empty parentheses. Note that parentheses are sometimes required, such as when a method has zero arguments, so you may find it simplest to always use parentheses.

Note	Gradle has a convention whereby if a method has the same name as a collection-based property, then the method appends its values to that collection.

Blocks

Blocks are also methods, just with specific types for the last argument.

<obj>.<name> {
     ...
}

<obj>.<name>(<arg>, <arg>) {
     ...
}

Examples

plugins {
    id 'java-library'
}

configurations {
    assets
}

sourceSets {
    main {
        java {
            srcDirs = ['src']
        }
    }
}

dependencies {
    implementation project(':util')
}

Blocks are a mechanism for configuring multiple aspects of a build element in one go. They also provide a way to nest configuration, leading to a form of structured data.

There are two important aspects of blocks that you should understand:

They are implemented as methods with specific signatures.
They can change the target ("delegate") of unqualified methods and properties.

Both are based on Groovy language features and we explain them in the following sections.

Block method signatures

You can easily identify a method as the implementation behind a block by its signature, or more specifically, its argument types. If a method corresponds to a block:

It must have at least one argument.
The last argument must be of type groovy.lang.Closure or org.gradle.api.Action.

For example, Project.copy(Action) matches these requirements, so you can use the syntax:

copy {
    into layout.buildDirectory.dir("tmp")
    from 'custom-resources'
}

That leads to the question of how into() and from() work. They’re clearly methods, but where would you find them in the API documentation? The answer comes from understanding object delegation.

Delegation

The section on properties lists where unqualified properties might be found. One common place is on the Project object. But there is an alternative source for those unqualified properties and methods inside a block: the block’s delegate object.

To help explain this concept, consider the last example from the previous section:

copy {
    into layout.buildDirectory.dir("tmp")
    from 'custom-resources'
}

All the methods and properties in this example are unqualified. You can easily find copy() and layout in the Project API documentation, but what about into() and from()? These are resolved against the delegate of the copy {} block. What is the type of that delegate? You’ll need to check the API documentation for that.

There are two ways to determine the delegate type, depending on the signature of the block method:

For Action arguments, look at the type’s parameter.

In the example above, the method signature is copy(Action<? super CopySpec>) and it’s the bit inside the angle brackets that tells you the delegate type — CopySpec in this case.
For Closure arguments, the documentation will explicitly say in the description what type is being configured or what type the delegate it (different terminology for the same thing).

Hence you can find both into() and from() on CopySpec. You might even notice that both of those methods have variants that take an Action as their last argument, which means you can use block syntax with them.

All new Gradle APIs declare an Action argument type rather than Closure, which makes it very easy to pick out the delegate type. Even older APIs have an Action variant in addition to the old Closure one.

Local variables

def <name> = <value>        // Untyped variable
<type> <name> = <value>     // Typed variable

Examples

def i = 1
String errorMsg = 'Failed, because reasons'

Local variables are a Groovy construct — unlike extra properties — that can be used to share values within a build script.

Caution

Avoid using local variables in the root of the project, i.e. as pseudo project properties. They cannot be read outside of the build script and Gradle has no knowledge of them.

Within a narrower context — such as configuring a task — local variables can occasionally be helpful.

Kotlin

Gradle Kotlin DSL Primer

Gradle’s Kotlin DSL offers an alternative to the traditional Groovy DSL, delivering an enhanced editing experience in supported IDEs with features like better content assist, refactoring, and documentation.

This chapter explores the key Kotlin DSL constructs and demonstrates how to use them to interact with the Gradle API.

Tip	If you are interested in migrating an existing Gradle build to the Kotlin DSL, please also check out the dedicated migration page.

Prerequisites

The embedded Kotlin compiler supports the platforms and architectures listed in the Kotlin/Native target support documentation.
Familiarity with Kotlin syntax and basic language features is recommended. Refer to the Kotlin documentation and Kotlin Koans to learn the basics.
Using the plugins {} block to declare Gradle plugins is highly recommended as it significantly improves the editing experience.

IDE support

The Kotlin DSL is fully supported by IntelliJ IDEA and Android Studio. While other IDEs lack advanced tools for editing Kotlin DSL files, you can still import Kotlin-DSL-based builds and work with them as usual.

Build import

Syntax highlighting ¹

Semantic editor ²

IntelliJ IDEA

✓

Android Studio

✓

Eclipse IDE

✓

✖

CLion

✓

✖

Apache NetBeans

✓

✖

Visual Studio Code ^(LSP)

✓

✖

Visual Studio

✓

✖

¹ ^Kotlin ^syntax ^highlighting ⁱⁿ ^Gradle ^Kotlin ^DSL ^scripts
² ^Code ^completion, ^navigation ^to ^sources, ^{documentation,} ^refactorings ^etc… ⁱⁿ ^Gradle ^Kotlin ^DSL ^scripts

As noted in the limitations, you must import your project using the Gradle model to enable content assist and refactoring tools for Kotlin DSL scripts in IntelliJ IDEA.

Builds with slow configuration time might affect the IDE responsiveness, so please check out the performance section to help resolve such issues.

Automatic build import vs. automatic reloading of script dependencies

Both IntelliJ IDEA and Android Studio will detect when you make changes to your build logic and offer two suggestions:

Import the whole build again:
Reload script dependencies when editing a build script:

We recommend disabling automatic build import while enabling automatic reloading of script dependencies. This approach provides early feedback when editing Gradle scripts while giving you control over when the entire build setup synchronizes with your IDE.

See the Troubleshooting section to learn more.

Kotlin DSL scripts

Just like its Groovy-based counterpart, the Kotlin DSL is built on Gradle’s Java API. Everything in a Kotlin DSL script is Kotlin code, compiled and executed by Gradle. Many of the objects, functions, and properties in your build scripts come from the Gradle API and the APIs of applied plugins.

Tip	Use the Kotlin DSL reference search to explore available members.

Script file names

Groovy DSL script files use the .gradle file name extension.
Kotlin DSL script files use the .gradle.kts file name extension.

To activate the Kotlin DSL, use the .gradle.kts extension for your build scripts instead of .gradle. This also applies to the settings file (e.g., settings.gradle.kts) and initialization scripts.

You can mix Groovy DSL and Kotlin DSL scripts within the same build. For example, a Kotlin DSL build script can apply a Groovy DSL one, and different projects in a multi-project build can use either.

To improve IDE support, we recommend following these conventions:

Name settings scripts (or any script backed by a Gradle Settings object) using the pattern *.settings.gradle.kts. This includes script plugins applied from settings scripts.
Name initialization scripts using the pattern *.init.gradle.kts or simply init.gradle.kts.

This helps the IDE identify the object "backing" the script, whether it’s Project, Settings, or Gradle.

Implicit imports

All Kotlin DSL build scripts come with implicit imports, including:

The default Gradle API imports
The Kotlin DSL API, which includes types from the following packages:
- org.gradle.kotlin.dsl
- org.gradle.kotlin.dsl.plugins.dsl
- org.gradle.kotlin.dsl.precompile
- java.util.concurrent.Callable
- java.util.concurrent.TimeUnit
- java.math.BigDecimal
- java.math.BigInteger
- java.io.File
- javax.inject.Inject

Avoid Using Internal Kotlin DSL APIs

Using internal Kotlin DSL APIs in plugins and build scripts can break builds when either Gradle or plugins are updated.

The Kotlin DSL API extends the public Gradle API with types listed in the corresponding API docs found in the packages above (but not in their subpackages).

Compilation warnings

Gradle Kotlin DSL scripts are compiled by Gradle during the configuration phase of your build.

Deprecation warnings found by the Kotlin compiler are reported on the console when compiling the scripts:

> Configure project :
w: build.gradle.kts:4:5: 'getter for uploadTaskName: String!' is deprecated. Deprecated in Java

It is 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

Type-safe model accessors

The Groovy DSL allows you to reference many build model elements by name, even if they are defined at runtime, such as named configurations or source sets.

For example, when the Java plugin is applied, you can access the implementation configuration via configurations.implementation.

The Kotlin DSL replaces this dynamic resolution with type-safe model accessors, which work with model elements contributed by plugins.

Understanding when type-safe model accessors are available

The Kotlin DSL currently provides various sets of type-safe model accessors, each tailored to different scopes.

For the main project build scripts and precompiled project script plugins:

Type-safe model accessors Example

Dependency and artifact configurations

implementation and runtimeOnly (contributed by the Java Plugin)

Project extensions and conventions, and extensions on them

sourceSets

Extensions on the dependencies and repositories containers, and extensions on them

testImplementation (contributed by the Java Plugin), mavenCentral

Elements in the tasks and configurations containers

compileJava (contributed by the Java Plugin), test

Elements in project-extension containers

Source sets contributed by the Java Plugin that are added to the sourceSets container: sourceSets.main.java { setSrcDirs(listOf("src/main/java")) }

For the main project settings script and precompiled settings script plugins:

Type-safe model accessors Example

Project extensions and conventions, contributed by Settings plugins, and extensions on them

pluginManagement, dependencyResolutionManagement

Important

Initialization scripts and script plugins do not have type-safe model accessors. These limitations will be removed in a future Gradle release.

The set of type-safe model accessors available is determined right before evaluating the script body, immediately after the plugins {} block. Model elements contributed after that point, such as configurations defined in your build script, will not work with type-safe model accessors:

build.gradle.kts

// Applies the Java plugin
plugins {
    id("java")
}

repositories {
    mavenCentral()
}

// Access to 'implementation' (contributed by the Java plugin) works here:
dependencies {
    implementation("org.apache.commons:commons-lang3:3.12.0")
    testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher") // Add this if needed for runtime
}

// Add a custom configuration
configurations.create("customConfiguration")
// Type-safe accessors for 'customConfiguration' will NOT be available because it was created after the plugins block
dependencies {
    customConfiguration("com.google.guava:guava:32.1.2-jre") // ❌ Error: No type-safe accessor for 'customConfiguration'
}

However, this means you can use type-safe accessors for any model elements contributed by plugins that are applied by parent projects.

The following project build script demonstrates how you can access various configurations, extensions and other elements using type-safe accessors:

build.gradle.kts

plugins {
    `java-library`
}

dependencies {                              // (1)
    api("junit:junit:4.13")
    implementation("junit:junit:4.13")
    testImplementation("junit:junit:4.13")
}

configurations {                            // (1)
    implementation {
        resolutionStrategy.failOnVersionConflict()
    }
}

sourceSets {                                // (2)
    main {                                  // (3)
        java.srcDir("src/core/java")
    }
}

java {                                      // (4)
    sourceCompatibility = JavaVersion.VERSION_11
    targetCompatibility = JavaVersion.VERSION_11
}

tasks {
    test {                                  // (5)
        testLogging.showExceptions = true
        useJUnit()
    }
}

Uses type-safe accessors for the api, implementation and testImplementation dependency configurations contributed by the Java Library Plugin
Uses an accessor to configure the sourceSets project extension
Uses an accessor to configure the main source set
Uses an accessor to configure the java source for the main source set
Uses an accessor to configure the test task

Tip	Your IDE is aware of the type-safe accessors and will include them in its suggestions. This applies both at the top level of your build scripts, where most plugin extensions are added to the `Project` object, and within the blocks that configure an extension.

Note that accessors for elements of containers such as configurations, tasks, and sourceSets leverage Gradle’s configuration avoidance APIs. For example, on tasks, accessors are of type TaskProvider<T> and provide a lazy reference and lazy configuration of the underlying task.

Here are some examples illustrating when configuration avoidance applies:

build.gradle.kts

tasks.test {
    // lazy configuration
    useJUnitPlatform()
}

// Lazy reference
val testProvider: TaskProvider<Test> = tasks.test

testProvider {
    // lazy configuration
}

// Eagerly realized Test task, defeats configuration avoidance if done out of a lazy context
val test: Test = tasks.test.get()

For all other containers, accessors for elements are of type NamedDomainObjectProvider<T>, providing the same behavior:

build.gradle.kts

val mainSourceSetProvider: NamedDomainObjectProvider<SourceSet> = sourceSets.named("main")

Understanding what to do when type-safe model accessors are not available

Consider the sample build script shown above, which demonstrates the use of type-safe accessors. The following sample is identical, except it uses the apply() method to apply the plugin.

In this case, the build script cannot use type-safe accessors because the apply() call occurs in the body of the build script. You must use another techniques instead, as demonstrated here:

build.gradle.kts

apply(plugin = "java-library")

dependencies {
    "api"("junit:junit:4.13")
    "implementation"("junit:junit:4.13")
    "testImplementation"("junit:junit:4.13")
}

configurations {
    "implementation" {
        resolutionStrategy.failOnVersionConflict()
    }
}

configure<SourceSetContainer> {
    named("main") {
        java.srcDir("src/core/java")
    }
}

configure<JavaPluginExtension> {
    sourceCompatibility = JavaVersion.VERSION_11
    targetCompatibility = JavaVersion.VERSION_11
}

tasks {
    named<Test>("test") {
        testLogging.showExceptions = true
    }
}

Type-safe accessors are unavailable for model elements contributed by the following:

Plugins applied via the apply(plugin = "id") method.
The project build script.
Script plugins, via apply(from = "script-plugin.gradle.kts").
Plugins applied via cross-project configuration.

You cannot use type-safe accessors in binary Gradle plugins implemented in Kotlin.

If you can’t find a type-safe accessor, fall back to using the normal API for the corresponding types. To do so, you need to know the names and/or types of the configured model elements. We will now show you how these can be discovered by examining the script in detail.

Artifact configurations

The following sample demonstrates how to reference and configure artifact configurations without type-safe accessors:

build.gradle.kts

apply(plugin = "java-library")

dependencies {
    "api"("junit:junit:4.13")
    "implementation"("junit:junit:4.13")
    "testImplementation"("junit:junit:4.13")
}

configurations {
    "implementation" {
        resolutionStrategy.failOnVersionConflict()
    }
}

The code looks similar to that of the type-safe accessors, except that the configuration names are string literals. You can use string literals for configuration names in dependency declarations and within the configurations {} block.

While the IDE won’t be able to help you discover the available configurations, you can look them up either in the corresponding plugin’s documentation or by running ./gradlew dependencies.

Project extensions

Project extensions have both a name and a unique type. However, the Kotlin DSL only needs to know the type to configure them.

The following sample shows the sourceSets {} and java {} blocks from the original example build script. The configure<T>() function is used with the corresponding type:

build.gradle.kts

apply(plugin = "java-library")

configure<SourceSetContainer> {
    named("main") {
        java.srcDir("src/core/java")
    }
}

configure<JavaPluginExtension> {
    sourceCompatibility = JavaVersion.VERSION_11
    targetCompatibility = JavaVersion.VERSION_11
}

Note that sourceSets is a Gradle extension on Project of type SourceSetContainer. In the example above, java refers to the SourceSet.java property (a SourceDirectorySet), not the top-level JavaPluginExtension.

You can discover available extensions by either reviewing the documentation for the applied plugins or running ./gradlew kotlinDslAccessorsReport. The report generates the Kotlin code needed to access the model elements contributed by the applied plugins, providing both names and types.

As a last resort, you can check the plugin’s source code, though this should not be necessary in most cases.

You can also use the the<T>() function if you only need a reference to the extension without configuring it, or if you want to perform a one-line configuration:

build.gradle.kts

the<SourceSetContainer>()["main"].java.srcDir("src/main/java")

The snippet above also demonstrates one way to configure elements of a project extension that is a container.

Elements in project-extension containers

Container-based project extensions, such as SourceSetContainer, allow you to configure the elements they hold.

In our sample build script, we want to configure a source set named main within the source set container. We can do this by using the named() method instead of an accessor:

build.gradle.kts

apply(plugin = "java-library")

configure<SourceSetContainer> {
    named("main") {
        java.srcDir("src/core/java")
    }
}

All elements within a container-based project extension have a name, so you can use this technique in all such cases.

For project extensions and conventions, you can discover what elements are present in any container by either checking the documentation for the applied plugins or by running ./gradlew kotlinDslAccessorsReport.

As a last resort, you may also review the plugin’s source code to find out what it does.

Tasks

Tasks are not managed through a container-based project extension, but they are part of a container that behaves in a similar way.

This means that you can configure tasks in the same way as you do for source sets. The following example illustrates this approach:

build.gradle.kts

apply(plugin = "java-library")

tasks {
    named<Test>("test") {
        testLogging.showExceptions = true
    }
}

We are using the Gradle API to refer to tasks by name and type, rather than using accessors.

Note that it is necessary to specify the type of the task explicitly. If you don’t, the script won’t compile because the inferred type will be Task, not Test, and the testLogging property is specific to the Test task type.

However, you can omit the type if you only need to configure properties or call methods that are common to all tasks, i.e., those declared on the Task interface.

You can discover what tasks are available by running ./gradlew tasks.

To find out the type of a given task, run ./gradlew help --task <taskName>, as demonstrated here:

❯ ./gradlew help --task test
...
Type
     Test (org.gradle.api.tasks.testing.Test)

The IDE can assist you with the required imports, so you only need the simple names of the types, without the package name part. In this case, there’s no need to import the Test task type, as it is part of the Gradle API and is therefore imported implicitly.

Working with container objects

The Gradle build model makes extensive use of container objects (or simply "containers").

For example, configurations and tasks are containers that hold Configuration and Task objects, respectively. Community plugins also contribute containers, such as the android.buildTypes container contributed by the Android Plugin.

The Kotlin DSL provides multiple ways for build authors to interact with containers. We will explore each of these methods, using the tasks container as an example.

Tip	You can leverage the type-safe accessors described in another section when configuring existing elements on supported containers. That section also explains which containers support type-safe accessors.

Using the container API

All containers in Gradle implement NamedDomainObjectContainer<DomainObjectType>. Some containers can hold objects of different types and implement PolymorphicDomainObjectContainer<BaseType>. The simplest way to interact with containers is through these interfaces.

The following example demonstrates how you can use the named() method to configure existing tasks, and the register() method to create new tasks:

build.gradle.kts

tasks.named("check")                    // (1)
tasks.register("myTask1")               // (2)

tasks.named<JavaCompile>("compileJava") // (3)
tasks.register<Copy>("myCopy1")         // (4)

tasks.named("assemble") {               // (5)
    dependsOn(":myTask1")
}
tasks.register("myTask2") {             // (6)
    description = "Some meaningful words"
}

tasks.named<Test>("test") {             // (7)
    testLogging.showStackTraces = true
}
tasks.register<Copy>("myCopy2") {       // (8)
    from("source")
    into("destination")
}

Gets a reference of type Task to the existing task named check
Registers a new untyped task named myTask1
Gets a reference to the existing task named compileJava of type JavaCompile
Registers a new task named myCopy1 of type Copy
Gets a reference to the existing (untyped) task named assemble and configures it — you can only configure properties and methods that are available on Task with this syntax
Registers a new untyped task named myTask2 and configures it — you can only configure properties and methods that are available on Task in this case
Gets a reference to the existing task named test of type Test and configures it — in this case you have access to the properties and methods of the specified type
Registers a new task named myCopy2 of type Copy and configures it

Note	The above sample relies on the configuration avoidance APIs. If you need or want to eagerly configure or register container elements, simply replace `named()` with `getByName()` and `register()` with `create()`.

Configuring multiple container elements together

When configuring several elements of a container, you can group interactions in a block to avoid repeating the container’s name on each interaction.

The following example demonstrates a combination of type-safe accessors and the container API:

build.gradle.kts

tasks {
    test {
        testLogging.showStackTraces = true
    }
    val myCheck = register("myCheck") {
        doLast { /* assert on something meaningful */ }
    }
    check {
        dependsOn(myCheck)
    }
    register("myHelp") {
        doLast { /* do something helpful */ }
    }
}

Working with extra properties

Extra properties are available on any object that implements the ExtensionAware interface.

The Kotlin DSL provides the extra accessor for working with extra properties as a map:

build.gradle.kts

extra["myNewProperty"] = "initial value"  // (1)

val myExtraProperty = extra["myNewProperty"] as String  // (2)
val myExtraNullableProperty = extra["myNullableProperty"] as String?  // (3)

Creates a new extra property called myNewProperty in the current context (the project in this case) and initializes it with the value "initial value"
Access an existing extra property from the current context (the project in this case)
Does the same as the previous line but allows the property to have a null value

This approach works for all Gradle scripts: project build scripts, script plugins, settings scripts, and initialization scripts.

You can also access extra properties on a root project from a subproject using the following syntax:

my-sub-project/build.gradle.kts

val myNewProperty = rootProject.extra["myNewProperty"] as String  // (1)

Reads the root project’s myNewProperty extra property

Extra properties aren’t just limited to projects. For example, Task extends ExtensionAware, so you can attach extra properties to tasks as well.

Here’s an example that defines a new reportType on the test task and then uses that property to initialize another task:

build.gradle.kts

tasks {
    test {
        extra["reportType"] = "dev"  // (1)
        doLast {
            // Use 'reportType' for post-processing of reports
        }
    }

    register<Zip>("archiveTestReports") {
        from(test.map { it.reports.html.outputLocation })
        archiveAppendix = test.map { it.extra["reportType"] as String } // (2)
    }
}

Creates a new reportType extra property on the test task
Reads the test task’s reportType extra property to configure the archiveTestReports task

Working with Gradle types

Property, Provider, and NamedDomainObjectProvider are types that represent deferred and lazy evaluation of values and objects. The Kotlin DSL provides a specialized syntax for working with these types.

Using a `Property`

A property represents a value that can be set and read lazily:

Setting a value: property.set(value) or property = value
Accessing the value: property.get()

build.gradle.kts

val myProperty: Property<String> = project.objects.property(String::class.java)

myProperty.set("Hello, Gradle!") // Set the value
println(myProperty.get())        // Access the value

// Using .get() to read the value
val propValue: String = myProperty.get()
println(propValue)

// Using assignment syntax
myProperty = "Hi, Gradle!" // Set the value
println(myProperty.get())  // Access the value

Using a `Provider`

A provider represents a read-only, lazily-evaluated value:

Accessing the value: provider.get()
Chaining: provider.map { transform(it) }

build.gradle.kts

val versionProvider: Provider<String> = project.provider { "1.0.0" }

println(versionProvider.get()) // Access the value

// Chaining transformations
val majorVersion: Provider<String> = versionProvider.map { it.split(".")[0] }
println(majorVersion.get()) // Prints: "1"

Using a `NamedDomainObjectProvider`

A named domain object provider represents a lazily-evaluated named object from a Gradle container (like tasks or extensions):

Accessing the object: namedObjectProvider.get()
Configuring the object: namedObjectProvider.configure { … }

build.gradle.kts

val myTaskProvider: NamedDomainObjectProvider<Task> = tasks.named("build")

// Configuring the task
myTaskProvider.configure {
    doLast {
        println("Build task completed!")
    }
}

// Accessing the task
val myTask: Task = myTaskProvider.get()

Lazy property assignment

Gradle’s Kotlin DSL supports lazy property assignment using the = operator.

Lazy property assignment reduces verbosity when lazy properties are used. It works for properties that are publicly seen as final (without a setter) and have type Property or ConfigurableFileCollection. Since properties must be final, we generally recommend avoiding custom setters for properties with lazy types and, if possible, implementing such properties via an abstract getter.

Using the = operator is the preferred way to call set() in the Kotlin DSL:

build.gradle.kts

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

abstract class WriteJavaVersionTask : DefaultTask() {
    @get:Input
    abstract val javaVersion: Property<String>
    @get:OutputFile
    abstract val output: RegularFileProperty

    @TaskAction
    fun execute() {
        output.get().asFile.writeText("Java version: ${javaVersion.get()}")
    }
}

tasks.register<WriteJavaVersionTask>("writeJavaVersion") {
    javaVersion.set("17") // (1)
    javaVersion = "17" // (2)
    javaVersion = java.toolchain.languageVersion.map { it.toString() } // (3)
    output = layout.buildDirectory.file("writeJavaVersion/javaVersion.txt")
}

Set value with the .set() method
Set value with lazy property assignment using the = operator
The = operator can be used also for assigning lazy values

IDE support

Lazy property assignment is supported from IntelliJ 2022.3 and from Android Studio Giraffe.

Kotlin DSL Plugin

The Kotlin DSL Plugin provides a convenient way to develop Kotlin-based projects that contribute build logic. This includes buildSrc projects, included builds, and Gradle plugins.

The plugin achieves this by doing the following:

Applies the Kotlin Plugin, which adds support for compiling Kotlin source files.
Adds the kotlin-stdlib, kotlin-reflect, and gradleKotlinDsl() dependencies to the compileOnly and testImplementation configurations, enabling the use of those Kotlin libraries and the Gradle API in your Kotlin code.
Configures the Kotlin compiler with the same settings used for Kotlin DSL scripts, ensuring consistency between your build logic and those scripts:
- Adds Kotlin compiler arguments,
- Registers the SAM-with-receiver Kotlin compiler plugin.
Enables support for precompiled script plugins.

Each Gradle release is meant to be used with a specific version of the kotlin-dsl plugin. Compatibility between arbitrary Gradle releases and kotlin-dsl plugin versions is not guaranteed. Using an unexpected version of the kotlin-dsl plugin will emit a warning and can cause hard-to-diagnose problems.

This is the basic configuration you need to use the plugin:

buildSrc/build.gradle.kts

plugins {
    `kotlin-dsl`
}

repositories {
    // The org.jetbrains.kotlin.jvm plugin requires a repository
    // where to download the Kotlin compiler dependencies from.
    mavenCentral()
}

The Kotlin DSL Plugin leverages Java Toolchains. By default, the code will target Java 8.

Embedded Kotlin

Gradle embeds Kotlin in order to provide support for Kotlin-based scripts.

Kotlin versions

Gradle ships with kotlin-compiler-embeddable plus matching versions of kotlin-stdlib and kotlin-reflect libraries. For details, see the Kotlin section of Gradle’s compatibility matrix. The kotlin package from those modules is visible through the Gradle classpath.

The compatibility guarantees provided by Kotlin apply for both backward and forward compatibility.

Backward compatibility

Our approach is to only make backward-incompatible Kotlin upgrades with major Gradle releases. We clearly document the Kotlin version shipped with each release and announce upgrade plans ahead of major releases.

Plugin authors aiming to maintain compatibility with older Gradle versions must limit their API usage to what is supported by those versions. This is no different from working with any new API in Gradle. For example, if a new API for dependency resolution is introduced, a plugin must either drop support for older Gradle versions or organize its code to conditionally execute the new code path on compatible versions.

Forward compatibility

The primary compatibility concern lies between the external kotlin-gradle-plugin version and the kotlin-stdlib version shipped with Gradle. More broadly, this applies to any plugin that transitively depends on kotlin-stdlib and its version provided by Gradle. As long as the versions are compatible, everything should work as expected. This issue will diminish as the Kotlin language matures.

Kotlin compiler arguments

The following Kotlin compiler arguments are used for compiling Kotlin DSL scripts, as well as Kotlin sources and scripts in projects with the kotlin-dsl plugin applied:

-java-parameters: Generate metadata for Java >= 1.8 reflection on method parameters. See Kotlin/JVM compiler options in the Kotlin documentation for more information.
-jvm-default=enable: Makes all non-abstract members of Kotlin interfaces default for the Java classes implementing them. This is to provide a better interoperability with Java and Groovy for plugins written in Kotlin. See Default methods in interfaces in the Kotlin documentation for more information.
-Xsam-conversions=class: Sets up the implementation strategy for SAM (single abstract method) conversion to always generate anonymous classes, instead of using the invokedynamic JVM instruction. This is to provide a better support for configuration cache and incremental build. See KT-44912 in the Kotlin issue tracker for more information.
-Xjsr305=strict & -Xjspecify-annotations=strict: Sets up Kotlin’s Java interoperability to strictly follow JSR-305 and JSpecify annotations for increased null safety. See Calling Java code from Kotlin in the Kotlin documentation for more information.

Interoperability

When mixing languages in your build logic, you may have to cross language boundaries. An extreme example would be a build that uses tasks and plugins that are implemented in Java, Groovy and Kotlin, while also using both Kotlin DSL and Groovy DSL build scripts.

Kotlin is designed with Java Interoperability in mind. Existing Java code can be called from Kotlin in a natural way, and Kotlin code can be used from Java rather smoothly as well.

— Kotlin reference documentation

Both calling Java from Kotlin and calling Kotlin from Java are very well covered in the Kotlin reference documentation.

The same mostly applies to interoperability with Groovy code. In addition, the Kotlin DSL provides several ways to opt into Groovy semantics, which we look at next.

Static extensions

Both the Groovy and Kotlin languages support extending existing classes via Groovy Extension modules and Kotlin extensions.

To call a Kotlin extension function from Groovy, call it as a static function, passing the receiver as the first parameter:

build.gradle

TheTargetTypeKt.kotlinExtensionFunction(receiver, "parameters", 42, aReference)

Kotlin extension functions are package-level functions. You can learn how to locate the name of the type declaring a given Kotlin extension in the Package-Level Functions section of the Kotlin reference documentation.

To call a Groovy extension method from Kotlin, the same approach applies: call it as a static function passing the receiver as the first parameter:

build.gradle.kts

TheTargetTypeGroovyExtension.groovyExtensionMethod(receiver, "parameters", 42, aReference)

Named parameters and default arguments

Both the Groovy and Kotlin languages support named function parameters and default arguments, although they are implemented very differently. Kotlin has fully-fledged support for both, as described in the Kotlin language reference under named arguments and default arguments. Groovy implements named arguments in a non-type-safe way based on a Map<String, ?> parameter, which means they cannot be combined with default arguments. In other words, you can only use one or the other in Groovy for any given method.

Calling Kotlin from Groovy

To call a Kotlin function that has named arguments from Groovy, just use a normal method call with positional parameters:

build.gradle

kotlinFunction("value1", "value2", 42)

There is no way to provide values by argument name.

To call a Kotlin function that has default arguments from Groovy, always pass values for all the function parameters.

Calling Groovy from Kotlin

To call a Groovy function with named arguments from Kotlin, you need to pass a Map<String, ?>, as shown in this example:

build.gradle.kts

groovyNamedArgumentTakingMethod(mapOf(
    "parameterName" to "value",
    "other" to 42,
    "and" to aReference))

To call a Groovy function with default arguments from Kotlin, always pass values for all the parameters.

Groovy closures from Kotlin

You may sometimes have to call Groovy methods that take Closure arguments from Kotlin code. For example, some third-party plugins written in Groovy expect closure arguments.

Note	Gradle plugins written in any language should prefer the type `Action<T>` type in place of closures. Groovy closures and Kotlin lambdas are automatically mapped to arguments of that type.

In order to provide a way to construct closures while preserving Kotlin’s strong typing, two helper methods exist:

closureOf<T> {}
delegateClosureOf<T> {}

Both methods are useful in different circumstances and depend upon the method you are passing the Closure instance into.

Some plugins expect simple closures, as with the Bintray plugin:

build.gradle.kts

bintray {
    pkg(closureOf<PackageConfig> {
        // Config for the package here
    })
}

In other cases, like with the Gretty Plugin when configuring farms, the plugin expects a delegate closure:

build.gradle.kts

farms {
    farm("OldCoreWar", delegateClosureOf<FarmExtension> {
        // Config for the war here
    })
}

There sometimes isn’t a good way to tell, from looking at the source code, which version to use. Usually, if you get a NullPointerException with closureOf<T> {}, using delegateClosureOf<T> {} will resolve the problem.

These two utility functions are useful for configuration closures, but some plugins might expect Groovy closures for other purposes. The KotlinClosure0 to KotlinClosure2 types allows adapting Kotlin functions to Groovy closures with more flexibility:

build.gradle.kts

somePlugin {

    // Adapt parameter-less function
    takingParameterLessClosure(KotlinClosure0({
        "result"
    }))

    // Adapt unary function
    takingUnaryClosure(KotlinClosure1<String, String>({
        "result from single parameter $this"
    }))

    // Adapt binary function
    takingBinaryClosure(KotlinClosure2<String, String, String>({ a, b ->
        "result from parameters $a and $b"
    }))
}

The Kotlin DSL Groovy Builder

If some plugin makes heavy use of Groovy metaprogramming, then using it from Kotlin or Java or any statically-compiled language can be very cumbersome.

The Kotlin DSL provides a withGroovyBuilder {} utility extension that attaches the Groovy metaprogramming semantics to objects of type Any.

The following example demonstrates several features of the method on the object target:

build.gradle.kts

target.withGroovyBuilder {                                          // (1)

    // GroovyObject methods available                               // (2)
    if (hasProperty("foo")) { /*...*/ }
    val foo = getProperty("foo")
    setProperty("foo", "bar")
    invokeMethod("name", arrayOf("parameters", 42, aReference))

    // Kotlin DSL utilities
    "name"("parameters", 42, aReference)                            // (3)
        "blockName" {                                               // (4)
            // Same Groovy Builder semantics on `blockName`
        }
    "another"("name" to "example", "url" to "https://example.com/") // (5)
}

The receiver is a GroovyObject and provides Kotlin helpers
The GroovyObject API is available
Invoke the methodName method, passing some parameters
Configure the blockName property, maps to a Closure taking method invocation
Invoke another method taking named arguments, maps to a Groovy named arguments Map<String, ?> taking method invocation

Using a Groovy script

Another option when dealing with problematic plugins that assume a Groovy DSL build script is to configure them in a Groovy DSL build script that is applied from the main Kotlin DSL build script:

dynamic-groovy-plugin-configuration.gradle

native {    // (1)
    dynamic {
        groovy as Usual
    }
}

build.gradle.kts

plugins {
    id("dynamic-groovy-plugin") version "1.0"   // (2)
}
apply(from = "dynamic-groovy-plugin-configuration.gradle")  // (3)

The Groovy script uses dynamic Groovy to configure plugin
The Kotlin build script requests and applies the plugin
The Kotlin build script applies the Groovy script

Troubleshooting

The IDE support is provided by two components:

Kotlin Plugin (used by IntelliJ IDEA/Android Studio).
Gradle.

The level of support varies based on the versions of each.

If you encounter issues, first run ./gradlew tasks from the command line to determine if the problem is specific to the IDE. If the issue persists on the command line, it likely originates from the build itself rather than IDE integration.

However, if the build runs successfully on the command line but your script editor reports errors, try restarting your IDE and invalidating its caches.

If the issue persists, and you suspect a problem with the Kotlin DSL script editor, try the following:

Run ./gradlew tasks to gather more details.
Check the logs in one of these locations:
- $HOME/Library/Logs/gradle-kotlin-dsl on macOS
- $HOME/.gradle-kotlin-dsl/log on Linux
- $HOME/AppData/Local/gradle-kotlin-dsl/log on Windows
Report the issue on the Gradle issue tracker, including as much detail as possible.

From version 5.1 onward, the log directory is automatically cleaned. Logs are checked periodically (at most, every 24 hours), and files are deleted if unused for 7 days.

If this doesn’t help pinpoint the problem, you can enable the org.gradle.kotlin.dsl.logging.tapi system property in your IDE. This causes the Gradle Daemon to log additional details in its log file located at $HOME/.gradle/daemon.

In IntelliJ IDEA, enable this property by navigating to Help > Edit Custom VM Options… and adding: -Dorg.gradle.kotlin.dsl.logging.tapi=true.

For IDE problems outside the Kotlin DSL script editor, please open issues in the corresponding IDE’s issue tracker:

Lastly, if you face problems with Gradle itself or with the Kotlin DSL, please open issues on the Gradle issue tracker.

Limitations

The Kotlin DSL is known to be slower than the Groovy DSL on first use, for example with clean checkouts or on ephemeral continuous integration agents. Changing something in the buildSrc directory also has an impact as it invalidates build-script caching. The main reason for this is the slower script compilation for Kotlin DSL.
In IntelliJ IDEA, you must import your project from the Gradle model in order to get content assist and refactoring support for your Kotlin DSL build scripts.
Kotlin DSL script compilation avoidance has known issues. If you encounter problems, it can be disabled by setting the org.gradle.kotlin.dsl.scriptCompilationAvoidance system property to false.
The Kotlin DSL will not support the model {} block, which is part of the discontinued Gradle Software Model.

If you run into trouble or discover a suspected bug, please report the issue in the Gradle issue tracker.

Migrating build logic from Groovy to Kotlin

This section will walk you through converting your Groovy-based Gradle build scripts to Kotlin.

Gradle’s newer Kotlin DSL provides a pleasant editing experience in supported IDEs: content-assist, refactoring, documentation, and more.

Tip

Please also read the Gradle Kotlin DSL Primer to learn the specificities, limitations and usage of the Gradle Kotlin DSL.

The rest of the user manual contain build script excerpts that demonstrate both the Groovy DSL and the Kotlin DSL. This is the best place where to find how to do this and what with each DSL ; and it covers all Gradle features from using plugins to customizing the dependency resolution behavior.

Before you start migrating

Please read: It’s helpful to understand the following important information before you migrate:

Using the latest versions of Gradle, applied plugins, and your IDE should be your first move.
Kotlin DSL is fully supported in Intellij IDEA and Android Studio. Other IDEs, such as Eclipse or NetBeans, do not yet provide helpful tools for editing Gradle Kotlin DSL files, however, importing and working with Kotlin DSL-based builds work as usual.
In IntelliJ IDEA, you must import your project from the Gradle model to get content-assist and refactoring tools for Kotlin DSL scripts.
There are some situations where the Kotlin DSL is slower. First use, on clean checkouts or ephemeral CI agents for example, are known to be slower. The same applies to the scenario in which something in the buildSrc directory changes, which invalidates build-script caching. Builds with slow configuration time might affect the IDE responsiveness, please check out the documentation on Gradle performance.
You must run Gradle with Java 8 or higher. Java 7 is not supported.
The embedded Kotlin compiler is known to work on Linux, macOS, Windows, Cygwin, FreeBSD and Solaris on x86-64 architectures.
Knowledge of Kotlin syntax and basic language features is very helpful. The Kotlin reference documentation and Kotlin Koans should be useful to you.
Use of the plugins {} block to declare Gradle plugins significantly improves the editing experience, and is highly recommended. Consider adopting it in your Groovy build scripts before converting them to Kotlin.
The Kotlin DSL will not support model {} elements. This is part of the discontinued Gradle Software Model.

Read more in the Gradle Kotlin DSL Primer.

If you run to trouble or a suspected bug, please take advantage of the gradle/gradle issue tracker.

You don’t have to migrate all at once! Both Groovy and Kotlin-based build scripts can apply other scripts of either language. You can find inspiration for any Gradle features not covered in the Kotlin DSL samples.

Prepare your Groovy scripts

Some simple Kotlin and Groovy language differences can make converting scripts tedious:

Groovy strings can be quoted with single quotes 'string' or double quotes "string" whereas Kotlin requires double quotes "string".
Groovy allows to omit parentheses when invoking functions whereas Kotlin always requires the parentheses.
The Gradle Groovy DSL allows to omit the = assignment operator when assigning properties whereas Kotlin always requires the assignment operator.

As a first migration step, it is recommended to prepare your Groovy build scripts by

unifying quotes using double quotes,
disambiguating function invocations and property assignments (using respectively parentheses and assignment operator).

The former can easily be done by searching for ' and replacing by ". For example,

group = 'com.acme'
dependencies {
    implementation 'com.acme:example:1.0'
}

becomes:

group "com.acme"
dependencies {
    implementation "com.acme:example:1.0"
}

The next step is a bit more involved as it may not be trivial to distinguish function invocations and property assignments in a Groovy script. A good strategy is to make all ambiguous statements property assignments first and then fix the build by turning the failing ones to function invocations.

For example,

group "com.acme"
dependencies {
    implementation "com.acme:example:1.0"
}

becomes: