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 either remove that setting or set android.builtInKotlin=true to enable it.

Built-in Kotlin requires you to make 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.

That is because built-in Kotlin requires you to make some changes to your project. To resolve this error, perform the following steps.

1. Remove the kotlin-android plugin
2. Migrate the kotlin-kapt plugin if necessary
3. Migrate the kotlinOptions{} block 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're using 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're using 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

If you're using the org.jetbrains.kotlin.kapt (or kotlin-kapt) in your build files, this plugin won't be compatible with built-in Kotlin. You need to replace this plugin with the com.android.legacy-kapt plugin, using the same version as your current 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 kotlinOptions{} block if necessary

If you're using 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
    }
}

Report issues

After completing the previous steps, if you run into issues, check out the known issues in the description of 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 built-in Kotlin. 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.

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.experimental.built-in-kotlin plugin to the module you want to enable built-in Kotlin, using the same version as your current Android Gradle plugin.

3. Perform 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.experimental.built-in-kotlin plugin in your build files.