Migrate your build configuration from Groovy to KTS

Kotlin script (KTS) is preferred over Groovy for writing Gradle scripts because Kotlin is more readable and offers better compile-time checking and IDE support. Android Gradle plugin 4.0 added support for using KTS in your Gradle build configuration.

This page provides basic information about converting your Android app's Gradle build files from Groovy to KTS. We recommend you do the steps in the order listed. See also Gradle's migration guide and Kotlin DSL Primer. If you're migrating multiple projects, start with your smallest project so you gain experience, and then continue from there.

Common terms

KTS: Refers to Kotlin script, a flavor of the Kotlin language used by Gradle in build configuration files. Kotlin script is Kotlin code that can be run from the command line.

Kotlin DSL: Refers primarily to the Android Gradle plugin Kotlin DSL or, occasionally, to the underlying Gradle Kotlin DSL.

In the context of migrating from Groovy, the terms "KTS" and "Kotlin DSL" can be used interchangeably. In other words, converting an Android project from Groovy to KTS or from Groovy to the Kotlin DSL is the same thing.

Script file naming

Script file extension names are based on the language the build file is written in:

Gradle build files written in Groovy use the .gradle file name extension.
Gradle build files written in Kotlin use the .gradle.kts file name extension.

Convert the syntax

There are some general differences in syntax between Groovy and Kotlin, so you need to apply these changes throughout your build scripts.

Add parentheses to method calls

Groovy lets you to omit parentheses in method calls, while Kotlin requires them. To migrate your configuration, add parentheses to these sorts of method calls. This code shows how to configure a setting in Groovy:

compileSdkVersion 30

This is the same code written in Kotlin:

compileSdkVersion(30)

Add `=` to assignment calls

The Gradle Groovy DSL lets you to omit the assignment operator = when assigning properties, whereas Kotlin requires it. This code shows how to assign properties in Groovy:

java {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
}

This code shows how to assign properties in Kotlin:

java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

Convert strings

Here are the string differences between Groovy and Kotlin:

Double quotes for strings: While Groovy allows strings to be defined using single quotes, Kotlin requires double quotes.
String interpolation on dotted expressions: In Groovy, you can use just the $ prefix for string interpolations on dotted expressions, but Kotlin requires that you wrap the dotted expressions with curly braces. For example, in Groovy you can use $project.rootDir as shown in the following snippet:
```
    myRootDirectory = "$project.rootDir/tools/proguard-rules-debug.pro"
    
```
In Kotlin, however, the preceding code calls toString() on project, not on project.rootDir. To get the value of the root directory, wrap the ${project.rootDir} expression with curly braces:
```
    myRootDirectory = "${project.rootDir}/tools/proguard-rules-debug.pro"
    
```
To learn more, see String templates in the Kotlin documentation.

Rename file extensions

Append .kts to each build file as you migrate its contents. For example, select a build file, like the settings.gradle file. Rename the file to settings.gradle.kts and convert the file's contents to KTS. Make sure your project still compiles after the migration of each build file.

Migrate your smallest files first, gain experience, and then move on. You can have a mix of KTS and Groovy build files in a project, so take your time to carefully make the move.

Replace `def` with `val` or `var`

Replace def with val or var, which is how you define variables in Kotlin. This is a variable declaration in Groovy:

def building64Bit = false

This is the same code written in Kotlin:

val building64Bit = false

Prefix boolean properties with `is`

Groovy uses property deduction logic based on the property names. For a boolean property foo, its deduced methods can be getFoo, setFoo, or isFoo. Thus once converted to Kotlin, you need to change the property names to the deduced methods that are not supported by Kotlin. For example, for buildTypes DSL boolean elements, you need to prefix them with is. This code shows how to set boolean properties in Groovy:

android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true
            ...
        }
        debug {
            debuggable true
            ...
        }
    ...

The following is the same code in Kotlin. Note that the properties are prefixed by is.

android {
    buildTypes {
        getByName("release") {
            isMinifyEnabled = true
            isShrinkResources = true
            ...
        }
        getByName("debug") {
            isDebuggable = true
            ...
        }
    ...

Convert lists and maps

Lists and maps in Groovy and Kotlin are defined using different syntax. Groovy uses [], while Kotlin calls collection creation methods explicitly using listOf or mapOf. Make sure to replace [] with listOf or mapOf when migrating.

Here's how to define a list in Groovy versus Kotlin:

jvmOptions += ["-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError</code>"]

This is the same code written in Kotlin:

jvmOptions += listOf("-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError")

Here's how to define a map in Groovy versus Kotlin:

def myMap = [key1: 'value1', key2: 'value2']

This is the same code written in Kotlin:

val myMap = mapOf("key1" to "value1", "key2" to "value2")

Configure build types

In the Kotlin DSL only the debug and release build types are available implicitly. All other custom build types must be created manually.

In Groovy you can use the debug, release, and certain other build types without creating them first. The following code snippet shows a configuration with the debug, release, and benchmark build types in Groovy.

buildTypes {
 debug {
   ...
 }
 release {
   ...
 }
 benchmark {
   ...
 }
}

To create the equivalent configuration in KTS, you must explicitly create the benchmark build type.

buildTypes {
 debug {
   ...
 }

 release {
   ...
 }
 register("benchmark") {
    ...
 }
}

Convert the plugins block

Applying plugins is similar in Groovy and KTS. In both KTS and Groovy, we recommend using the plugins {} block instead of using the buildscript with apply to apply plugins.

When you use the plugins {} block in your build files, Android Studio is aware of the context even when the build fails. This context helps make fixes to your KTS files because it allows the Studio IDE to perform code completion and provide other helpful suggestions.

The following code shows how to apply plugins in Groovy when you're using Gradle Version Catalogs:

// Top-level build.gradle file
plugins {
   alias libs.plugins.android.application apply false
   ...
}

// Module-level build.gradle file
plugins {
   alias libs.plugins.android.application
   ...
}

The following code shows how to do the same in Kotlin:

// Top-level build.gradle.kts file
plugins {
   alias(libs.plugins.android.application) apply false
   ...
}

// Module-level build.gradle.kts file
plugins {
   alias(libs.plugins.android.application)
   ...
}

The following code shows how to apply plugins in Groovy when you're not using Gradle Version Catalogs:

// Top-level build.gradle file
plugins {
   id 'com.android.application' version '7.3.0' apply false
   ...
}

// Module-level build.gradle file
plugins {
   id 'com.android.application'
   ...
}

The following code shows how to do the same in Kotlin:

// Top-level build.gradle.kts file
plugins {
   id("com.android.application") version '7.3.0' apply false
   ...
}

// Module-level build.gradle.kts file
plugins {
   id("com.android.application")
   ...
}

For more details about the plugins {} block, see Applying plugins in the Gradle documentation.

Miscellaneous

For Kotlin code samples for other functionalities, see the following documentation pages:

If you have a ProGuard configuration, refer to Enable shrinking, obfuscation, and optimization.
If you have a signingConfig {} block, refer to Remove signing information from your build files.
If you use project-wide properties, refer to Configure project-wide properties.

Known issues

At present, a known issue is that build speed might be slower with KTS than with Groovy.

How to report issues

For instructions on how to provide the info we need to triage your issue, see Details for build tools and Gradle bugs. Then, file a bug using the Google public issue tracker.

More resources

For a working example of Gradle build files written with KTS, see the Now In Android sample app on GitHub.

Migrate your build configuration from Groovy to KTS

Common terms

Script file naming

Convert the syntax

Add parentheses to method calls

Add = to assignment calls

Convert strings

Rename file extensions

Replace def with val or var

Prefix boolean properties with is

Convert lists and maps

Configure build types

Convert the plugins block

Miscellaneous

Known issues

How to report issues

More resources

Add `=` to assignment calls

Replace `def` with `val` or `var`

Prefix boolean properties with `is`