The Android Target: the Android-KMP Library Plugin and AGP 9

Android is the one target in a KMP project that is not built by Kotlin alone: it is built by AGP, a separate Gradle plugin with its own release train, its own DSL and its own variant model. Historically the two plugins were wired together through an adapter inside the Kotlin plugin.

The table summarizes how the three ways of getting an Android target compare.

The plugin is only for library modules. Google states there is no direct replacement for configuring a Kotlin Multiplatform module with com.android.application; the documented migration is to extract the Android app into a separate Gradle module. That is the single biggest structural consequence of AGP 9 and the reason the recommended layout of this section has an androidApp module (see Project Structure, Targets, Source Sets and the Hierarchy Template).

The following diagram contrasts the module graph of TrailMate Everywhere in the legacy single-module layout (typical of projects generated before AGP 9, where one composeApp module held the shared code and the Android entry point) with the layout that AGP 9 requires.

Three things changed. The Android application plugin moved out of the shared module and into androidApp; the shared modules switched from com.android.library (or the application plugin) to the Android-KMP library plugin; and every other platform entry point (iosApp, desktopApp, webApp) stayed an entry point rather than becoming a Gradle dependency of the shared code.

Applying the plugin takes three edits: declare it in the version catalog, register it in the root build file with apply false so that all subprojects share one plugin classpath, and apply it in each shared module.

See Android Developers — Set up the Android Gradle library plugin for KMP.

In the root build.gradle.kts, add the same aliases with apply false.

The shared module then combines the Kotlin Multiplatform plugin with the new Android plugin and configures the Android target in an android {} block inside kotlin {}:

See Android Developers — Set up the Android Gradle library plugin for KMP.

There is no top-level android {} extension any more. The Android DSL lives inside the target, which is why the same configuration reads kotlin { android { namespace = …​ } }. Some older JetBrains tutorials spell the block androidLibrary {}; the current Android Developers documentation uses android {}, and so does this section.

The three properties in the example are the minimum:

There is no targetSdk in a library: it is an application concept and belongs to androidApp. There is also no applicationId, versionCode or versionName, for the same reason.

The most visible difference from com.android.library is that the Android-KMP plugin produces exactly one variant. There are no build types (debug, release), no product flavors and no flavor dimensions. A KMP library is published as one .aar that every consumer variant resolves against, so variants of the library itself add cost without benefit. Dropping them makes configuration simpler and, according to Google, improves build performance and IDE integration.

The following table lists what disappears with variants and the documented replacement.

To keep builds lean, the plugin disables everything that most shared modules do not need. Each feature is enabled explicitly inside kotlin { android { } }. The table gives the overview; the subsections show each one.

Compose Preview, layout inspection and similar IDE tools need androidx.compose.ui:ui-tooling at runtime, but that dependency must not leak into the published library. In a legacy module you wrote debugImplementation(…​), relying on the debug build type. A single-variant library has no debug build type, so the dependency is added to the runtime classpath of the main Android compilation instead:

See Android Developers — Set up the Android Gradle library plugin for KMP.

The configuration name is quoted because the top-level dependencies {} block has no type-safe accessor for it. The workaround is available from AGP 9.0.0-beta01. The androidApp module, which is a real application with a debug build type, keeps using debugImplementation for the same tooling.

An Android application module needs everything the single-variant library model removes: build types (debug and release signing), flavors, applicationId, versionCode, manifest placeholders and the packaging pipeline that produces .apk and .aab. The Android-KMP plugin deliberately has none of that, and AGP 9 no longer lets com.android.application coexist with the Kotlin Multiplatform plugin in one module. The consequence is structural and unavoidable:

This is the same pattern iOS has always had (the Xcode app depends on the Kotlin framework) and desktop and web entry points follow. It also removes a classic problem: a module that was both application and library made the Android entry point a build dependency of everything else. The recommended layout is discussed in Project Structure, Targets, Source Sets and the Hierarchy Template.

AGP 9.0 ships built-in Kotlin support and enables it by default: an Android module can compile Kotlin without applying org.jetbrains.kotlin.android (kotlin-android). Two consequences matter for KMP.

The androidApp build script of TrailMate Everywhere therefore looks like this: no Kotlin plugin line, the Compose compiler plugin for the UI, and a dependency on the shared UI module.

See Android Developers — Migrate to built-in Kotlin.

The app module uses the ordinary android {} block, with src/main as its source directory, exactly as in a native Android project; that is the right place for everything described in Project Structure, Gradle and Build Variants. Other built-in-Kotlin migration items (kotlin-kapt, android.kotlinOptions {}, kotlin.sourceSets {} in androidApp) are covered in that Android page and in the migration guide linked in the references.

The official recommendation is to migrate in two stages, verifying that the app runs after each, and to update AGP itself last. The steps below follow JetBrains' guide for the common case of one composeApp module that holds both the shared code and the Android entry point.

The name of the Android target DSL has changed twice, which causes real confusion when reading older snippets.

The practical reading: in a module with com.android.library, androidTarget() is still the (legacy) spelling; in a module with com.android.kotlin.multiplatform.library, the target is declared by the plugin and configured as kotlin { android { } }. Writing androidTarget() next to the new plugin is a common mistake and does not work. Existing androidTarget code on AGP 9 also needs the legacy variant API opt-in described above.

See Kotlin docs — Compatibility guide for Kotlin Multiplatform.

Before Kotlin 1.9.0 the Kotlin plugin named source sets after AGP’s: androidAndroidTest, androidTest, a src/main/kotlin directory and so on. The new Android source-set layout (introduced in Kotlin 1.8.0, default since 1.9.0) names them androidMain, androidUnitTest and androidInstrumentedTest and uses src/androidMain/kotlin and src/androidMain/AndroidManifest.xml. The deprecation cycle of the old layout ended in Kotlin 2.4.0:

If a project that still sets that property is upgraded to Kotlin 2.4.20, delete the property and apply the rename table: main to androidMain, test to androidUnitTest, androidTest to androidInstrumentedTest, and move the manifest from src/main/AndroidManifest.xml to src/androidMain/AndroidManifest.xml. A related change: in the new layout androidInstrumentedTest no longer implicitly depends on commonTest; if you want common tests to run as instrumented tests you must add dependsOn(commonTest) yourself. (With the Android-KMP plugin these two source sets are androidHostTest and androidDeviceTest, as described above.)

See Kotlin docs — Android source set layout.

Teams that centralize configuration in convention plugins (see Project Structure, Gradle and Build Variants for build-logic) must update them: the new plugin is not part of com.android.base, so checks like plugins.withId("com.android.base") no longer detect it, and its extension is not registered at the project level but lives inside the target. Google’s guide for plugin authors recommends reacting to the Kotlin Multiplatform plugin first and then to the target types:

See Android Developers — Add KMP module to a project (plugin author guidance).

Rules from the guide worth remembering:

For the Kotlin side of convention plugins and version catalogs in a multiplatform build, see Gradle Configuration, the Multiplatform DSL and Compatibility.