Migrate to built-in Kotlin

Android Gradle plugin 9.0 introduces built-in Kotlin support and enables it by default. That means you no longer have to apply the org.jetbrains.kotlin.android (or kotlin-android) plugin in your build files to compile Kotlin source files. With built-in Kotlin, your build files are simpler and you can avoid compatibility issues between AGP and the kotlin-android plugin.

Enable built-in Kotlin

You need AGP 9.0 or higher to have built-in Kotlin support. AGP 9.0 already enables built-in Kotlin for all your modules where you apply AGP, so you don't need to do anything to enable it. However, if you previously opted out of built-in Kotlin by setting android.builtInKotlin=false in the gradle.properties file, you need to remove that setting or set it to true.

Built-in Kotlin requires some changes to your project, so after you have built-in Kotlin enabled, follow the next steps to migrate your project.

Migration steps

After you upgrade your project from an older AGP version to AGP 9.0 or after you manually enable built-in Kotlin, you might see the following error message:

Failed to apply plugin 'org.jetbrains.kotlin.android'.
> Cannot add extension with name 'kotlin', as there is an extension already registered with that name.

...or

Failed to apply plugin 'com.jetbrains.kotlin.android'
> The 'org.jetbrains.kotlin.android' plugin is no longer required for Kotlin support since AGP 9.0.

This error occurs because built-in Kotlin requires some changes to your project. To resolve this error, follow these steps:

1. Remove the kotlin-android plugin
2. Migrate the kotlin-kapt plugin if necessary
3. Migrate the android.kotlinOptions{} DSL if necessary
4. Migrate the kotlin.sourceSets{} DSL if necessary

1. Remove the kotlin-android plugin

Remove the org.jetbrains.kotlin.android (or kotlin-android) plugin from the module-level build files where you apply it. The exact code to remove depends on whether you use version catalogs to declare plugins.

// Module-level build file
plugins {
    alias(libs.plugins.kotlin.android)
}

// Module-level build file
plugins {
    alias(libs.plugins.kotlin.android)
}

// Module-level build file
plugins {
    id("org.jetbrains.kotlin.android")
}

// Module-level build file
plugins {
    id 'org.jetbrains.kotlin.android'
}

Then, remove the plugin from your top-level build file:

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

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

// Top-level build file
plugins {
    id("org.jetbrains.kotlin.android") version "KOTLIN_VERSION" apply false
}

// Top-level build file
plugins {
    id 'org.jetbrains.kotlin.android' version 'KOTLIN_VERSION' apply false
}

If you use version catalogs, also remove the plugin definition from the version catalog TOML file (usually gradle/libs.versions.toml):

[plugins]
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "KOTLIN_VERSION" }

2. Migrate the kotlin-kapt plugin if necessary

The org.jetbrains.kotlin.kapt (or kotlin-kapt) plugin is incompatible with built-in Kotlin. If you use kapt, we recommend that you migrate your project to KSP.

If you can't migrate to KSP yet, replace the kotlin-kapt plugin with the com.android.legacy-kapt plugin, using the same version as your Android Gradle plugin.

For example, with version catalogs, update your version catalog TOML file as follows:

[plugins]
android-application = { id = "com.android.application", version.ref = "AGP_VERSION" }

# Add the following plugin definition
legacy-kapt = { id = "com.android.legacy-kapt", version.ref = "AGP_VERSION" }

# Remove the following plugin definition
kotlin-kapt = { id = "org.jetbrains.kotlin.kapt", version.ref = "KOTLIN_VERSION" }

Then, update your build files:

// Top-level build file
plugins {
    alias(libs.plugins.legacy.kapt) apply false
    alias(libs.plugins.kotlin.kapt) apply false
}

// Top-level build file
plugins {
    alias(libs.plugins.legacy.kapt) apply false
    alias(libs.plugins.kotlin.kapt) apply false
}

// Module-level build file
plugins {
    alias(libs.plugins.legacy.kapt)
    alias(libs.plugins.kotlin.kapt)
}

// Module-level build file
plugins {
    alias(libs.plugins.legacy.kapt)
    alias(libs.plugins.kotlin.kapt)
}

3. Migrate the android.kotlinOptions{} DSL if necessary

If you use the android.kotlinOptions{} DSL, you need to migrate it to the kotlin.compilerOptions{} DSL.

For example, update this code:

android {
    kotlinOptions {
        languageVersion = "2.0"
        jvmTarget = "11"
    }
}

android {
    kotlinOptions {
        languageVersion = "2.0"
        jvmTarget = "11"
    }
}

...to the new DSL:

kotlin {
    compilerOptions {
        languageVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0
        // Optional: Set jvmTarget
        // jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11
    }
}

kotlin {
    compilerOptions {
        languageVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0
        // Optional: Set jvmTarget
        // jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11
    }
}

4. Migrate the kotlin.sourceSets{} DSL if necessary

When you use the kotlin-android plugin, AGP lets you add additional Kotlin source directories using either the android.sourceSets{} DSL or the kotlin.sourceSets{} DSL. With the android.sourceSets{} DSL, you can add the directories to either the AndroidSourceSet.kotlin set or the AndroidSourceSet.java set.

With built-in Kotlin, the only supported option is to add the directories to the AndroidSourceSet.kotlin set using the android.sourceSets{} DSL. If you use unsupported options, migrate them as follows:

# Adding Kotlin source directories to kotlin.sourceSets is not supported
kotlin.sourceSets.named("main") {
    kotlin.srcDir("additionalSourceDirectory/kotlin")
}

# Adding Kotlin source directories to AndroidSourceSet.java is also not supported
android.sourceSets.named("main") {
    java.directories += "additionalSourceDirectory/kotlin"
}

# Add Kotlin source directories to AndroidSourceSet.kotlin
android.sourceSets.named("main") {
    kotlin.directories += "additionalSourceDirectory/kotlin"
}

# Adding Kotlin source directories to kotlin.sourceSets is not supported
kotlin.sourceSets.named("main") {
    kotlin.srcDir("additionalSourceDirectory/kotlin")
}

# Adding Kotlin source directories to AndroidSourceSet.java is also not supported
android.sourceSets.named("main") {
    java.directories.add("additionalSourceDirectory/kotlin")
}

# Add Kotlin source directories to AndroidSourceSet.kotlin
android.sourceSets.named("main") {
    kotlin.directories.add("additionalSourceDirectory/kotlin")
}

If you want to add a Kotlin source directory to a specific variant or if the directory is generated by a task, you can use the addStaticSourceDirectory or addGeneratedSourceDirectory methods in the variant API:

androidComponents.onVariants { variant ->
    variant.sources.kotlin!!.addStaticSourceDirectory("additionalSourceDirectory/kotlin")
    variant.sources.kotlin!!.addGeneratedSourceDirectory(TASK_PROVIDER, TASK_OUTPUT)
}

androidComponents.onVariants { variant ->
    variant.sources.kotlin!!.addStaticSourceDirectory("additionalSourceDirectory/kotlin")
    variant.sources.kotlin!!.addGeneratedSourceDirectory(TASK_PROVIDER, TASK_OUTPUT)
}

Report issues

If you encounter issues after completing the previous steps, review the known issues in issue #438678642 and give us feedback if needed.

Opt out of built-in Kotlin

If you are unable to migrate your project to use built-in Kotlin, set android.builtInKotlin=false in the gradle.properties file to temporarily disable it. When you do that, the build shows a warning reminding you to migrate to built-in Kotlin as you won't be able to disable built-in Kotlin in a future version of AGP 9.x before AGP 10.0.

Once you're ready to migrate your project, enable built-in Kotlin and follow the migration steps.

Module-by-module migration

The android.builtInKotlin Gradle property lets you enable or disable built-in Kotlin for all your modules where you apply AGP.

If migrating all your modules at once is challenging, you can migrate one module at a time:

1. Set android.builtInKotlin=false in the gradle.properties file to disable built-in Kotlin for all modules.

2. Apply the com.android.built-in-kotlin plugin to the module you want to enable built-in Kotlin, using the same version as your Android Gradle plugin.

3. Follow the previous migration steps to migrate this module to built-in Kotlin.

4. Once you've migrated all your modules, remove the android.builtInKotlin=false setting in gradle.properties and the com.android.built-in-kotlin plugin in your build files.

Option to selectively disable built-in Kotlin

Android Gradle plugin 9.0 enables built-in Kotlin for all modules where it is applied. We recommend disabling built-in Kotlin selectively for modules that don't have Kotlin sources in large projects. This removes both the Kotlin compilation task, which has a small build performance cost, and the automatic dependency on the Kotlin standard library.

To disable built-in Kotlin for a module, set enableKotlin = false in that module's build file:

android {
    enableKotlin = false
}

android {
    enableKotlin = false
}