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.

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 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.

With version catalogs

Kotlin

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

Groovy

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

No version catalogs

Kotlin

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

Groovy

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

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

With version catalogs

Kotlin

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

Groovy

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

No version catalogs

Kotlin

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

Groovy

// 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. We recommend that you migrate your project to KSP.

However, if you're not yet ready to use KSP, you need to replace the kotlin-kapt 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:

Kotlin

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

Groovy

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

Kotlin

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

Groovy

// 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:

Kotlin

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

Groovy

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

...to the new DSL:

Kotlin

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

Groovy

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, review 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 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 (together with the new DSL) 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.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. 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.experimental.built-in-kotlin plugin in your build files.