Yesterday I migrated a big 150,000-line project from AGP 8 to AGP 9. This was painful. This is probably the biggest migration effort that I had to undergo this year. So, to save you from the pain and dozens of wasted hours that I had to spend, I decided to write a full migration guide for you.

Be prepared, this migration will take some time, so you better start early. With AGP 9.0 already being in release, Google somehow expects you to already start using it yesterday. And they explicitly state that many of the existing APIs and workarounds that you can employ right now to delay the migration will stop working in summer 2026. So for big apps, you don’t have much time left.

Before we start, please keep in mind that despite AGP somehow being in production release, a lot of official plugins, such as the Hilt plugin and KSP, do not support AGP 9.0. If you use Hilt or KSP in your project, you will not be able to migrate without severe workarounds for now. If you’re reading this later than January 2026, just make sure to double-check if Hilt and KSP already have shipped AGP 9.0 support.

If you’re not blocked and still here, here is what you need to do to migrate your KMP project to AGP 9.0.

The biggest migration point: Dropped support for build types

Previously, we didn’t have build types on other platforms in KMP, but Android still had them. And in my opinion, they are one of the best features for security and performance that we had, but now they will not be supported and there is no replacement for them. You literally have to remove all build type-based code.

At first glance, this seems like a small problem, because teams usually don’t split a lot of code between source sets. It usually revolves around some debug performance and security checks. But there is a hidden caveat. BuildConfig values will stop working completely, because they are using the build types under the hood.

I had in my codebase dozens and dozens of places where I had a static top-level variable isDebuggable, delegating to BuildConfig.DEBUG, which I was checking and using a lot to add some extra rendering code, debugging, logging code, and to disable many of the security checks that the app had, which were only applicable on release.

Why I was using it as a static variable instead of something like context.isDebuggable is because the R8, when optimizing the release build of the app, would be able to remove all of that extra debug code without the need to create extra source sets, etc. This works well for KMP, where release and debug split wasn’t fully supported in the IDE for a long time.

But now this is completely impossible. This is a huge drawback for me personally, because I had to execute a humongous migration to replace all of those static global variable usages with a DI-injected interface, which was implemented using still build configuration, but in the application module, e.g.:

// in common domain KMP module
interface AppConfiguration {
val debuggable: Boolean
val backendUrl: String
val deeplinkDomain: String
val deeplinkSchema: String
val deeplinkPath: String
}

// in android app module
object AndroidAppConfiguration : AppConfiguration {
override val debuggable = BuildConfig.DEBUG
override val backendUrl = BuildConfig.BACKEND_URL
override val deeplinkDomain = BuildConfig.DEEPLINK_DOMAIN
override val deeplinkSchema = BuildConfig.DEEPLINK_SCHEMA
override val deeplinkPath = BuildConfig.DEEPLINK_PATH
}

This may result in a significant refactor, because I personally used the static isDebuggable flag in places where context/DI isn’t available. So, I had to sprinkle some terrible hacks with a global DI singleton object retrieval just to make the app work and then refactor the code.

When you’re done with this step, you must have 0 usages of BuildConfig, build types, or manifest placeholders in library modules. Note that codegen for build-time constants is still fine, just not per-build-type / Android one. You can create a custom Gradle task if you want that will generate a Kotlin file for you in ~20 lines.

I know that devs love BuildConfig.DEBUG a lot, and I also used it to manage deep link domains, backend URL substitution for debug and release builds, and all of that had to be refactored, which is why I urge you to stop using such code pattern with these static isDebuggable flags right now.

Also avoid using Context.isDebuggable boolean property, because that’s a runtime check which can be overridden by fraudulent actors, so it isn’t reliable. Don’t use it for security reasons. Remember - debug code should only be included in debug builds.

Remove all NDK and JNI code from library modules

The next step you have to take is remove all the NDK and JNI code that you have in library modules. I have a couple of places where I need to run some C++ code in my app, and those were previously located in the Android source set of the KMP library module where they were needed, because Apple source set didn’t need that native code, but Android did.

An official statement from Google is that NDK execution in library modules and C++ code execution and JNI will not be supported at all since AGP 9.0. So now, the only way you can preserve that code is if you move it to the application module. Again, that is something that is a huge drawback for me, but because Google didn’t give us any opportunities and didn’t want to listen, you have to comply if you do not want to get stuck on a deprecated AGP forever.

So before you even try to migrate to AGP 9.0, make sure you create an interface abstraction in your library module that will act as a proxy for all your NDK-enabled code. Then the implementation of that interface can live in the application module along with all the C++ code and inject the implementation into the DI graph so that your library module in the KMP code can just use that interface. At least this is what I did. This is the simplest solution to the problem, but if you know a better one, let me know.

The actual migration: Remove the old Kotlin Android plugin

Now we are finally finishing up with all the refactorings and approaching the actual migration. Start by removing the old Kotlin Android plugin. I had convention plugins set up, so it was reasonably easy for me to do, and migrate it to the new plugin. Read this docs page for what exactly to do.

When you remove it, also add the new plugin for Android Kotlin Multiplatform compatibility: com.android.kotlin.multiplatform.library. This is because your build will stop working and we need to migrate to the new DSL, which is only provided with this new plugin.

To fix gradle sync, do:

1. Update from the deprecated Android top level DSL android { } AND the deprecated kotlin.androidLibrary {} DSL to the new unified kotlin.android { } DSL. You should be able to copy-paste all of your previous configuration, like compile SDK, minimum SDK, and all of the other Android setup options which you previously had in the top-level Android block, and merge it with the code that you previously had in the kotlin.androidLibrary KMP setup. So now it’s just a single place. Note that library modules no longer support target SDK, which will only be governed by the app module.

id("sharedBuild")
id("detektConvention")
kotlin("multiplatform")
-    id("com.android.library")
+    id("com.android.kotlin.multiplatform.library")
}

kotlin {
configureMultiplatform(this)
}

-android {
-    configureAndroidLibrary(this)
-}
-

See how I had an extension function from my convention plugin, configureAndroidLibrary, and removed it? We can now completely ditch it. Everything will be inside the kotlin block. (configureMultiplatform in example above).

Next up, let’s update the said “configure multiplatform” function. This is based on this official doc page:

-    if (android) androidTarget {
-        publishLibraryVariants("release")
+    if (android) android {
+        namespace = [email protected]()
+        compileSdk = Config.compileSdk
+        minSdk = Config.minSdk
+        androidResources.enable = false
+        lint.warning.add("AutoboxingStateCreation")
+        packaging.resources.excludes.addAll(
+            listOf(
+                "/META-INF/{AL2.0,LGPL2.1}",
+                "DebugProbesKt.bin",
+                "META-INF/versions/9/previous-compilation-data.bin",
+            ),
+        )
+        withHostTest { isIncludeAndroidResources = true }
compilerOptions {
jvmTarget.set(Config.jvmTarget)
freeCompilerArgs.addAll(Config.jvmCompilerArgs)
}
+        optimization.consumerKeepRules.apply {
+            publish = true
+            file(Config.consumerProguardFile)
+        }
}
// ...
sourceSets {
commonTest.dependencies {
implementation(libs.requireBundle("unittest"))
}
-        if (android) androidUnitTest {
-            dependencies {
+        if (android) {
+            val androidHostTest = findByName("androidHostTest")
+            androidHostTest?.dependencies {
implementation(libs.requireLib("kotest-junit"))
}
}
}

In summary, what has changed here is that we had an androidTarget block which contained a small portion of our library module setup. That was replaced by the android block (not top-level, I know, confusing). And now we just put everything from our previous Android top-level block in here, and we removed the target SDK configuration, which was previously available here. Some syntax changed a bit, but this is only because I’m using convention plugins, so they don’t have all the same nice DSLs that you would have if you just configured this manually in your target module.

As you see, I put the new packaging excludes workarounds that have been there for ages into this new place. I moved the Lint warning configuration (that was used by Compose). Don’t forget to disable Android resources explicitly in this block because most of your KMP modules will not actually need Android resources, so I highly recommend you enable them on-demand in your feature modules where you actually need them. This will speed up the build times.

You can also see that instead of androidUnitTest configuration that we had, we just have androidHostTest, which is basically the same Android unit tests you’re used to. Host means that they run on the host machine, which is your PC. This is just a small syntax change, annoying but bearable.

Don’t forget to apply the consumer keep rules here, because a widely used best practice is to keep the consumer rules that are used by a particular library module together in the same place instead of dumping all of that into the application module. I was personally not happy about moving all of my consumer rules to the ProGuard rules file of the application module, so I just enabled consumer keep rules for every library module I have. This is especially useful for stuff like network modules, database modules, where I still have custom keep rules, and for modules which are supposed to use NDK and C++ code. If you don’t do this, the new plugin will no longer recognize and use your consumer keep rules, even if you place them there, so this is pretty important, as it will only surface on a release build, in runtime (possibly even in prod).

Now, as you might have probably guessed, the top-level android block will no longer be available for you. There will be no build variants, build flavors in those KMP library modules. So before, if you were following my instructions and already refactored all of those usages to move them to the application module and inject the necessary flags and variables via DI, you will hopefully not have a lot of trouble with this. But if you still do use some BuildConfig values, there is now no place to declare them. Same can be said for res values, manifest placeholders, etc. All of that is now not supported.

Important note for Compose Multiplatform resources

Previously, you saw that we disabled Android resources. But if you don’t enable Android resource processing, even for KMP modules with CMP resources, now in your feature modules and UI modules, your app will crash at runtime.

kotlin {
androidLibrary {
androidResources { enable = true }
}
}

Add this block to every module that you have that uses Compose Multiplatform resources. I had a convention plugin for feature modules, which made this super easy for me. More details are under the bug ticket on YouTrack.

Replace Android Unit Test with Android Host Test

The next step is to replace Android Unit Test dependency declarations with Android Host Test declarations. You can do this via an IDE search and replace using a simple regex.

-    androidUnitTestImplementation(libs.bundles.unittest)
+    androidHostTestImplementation(libs.bundles.unittest)

You’ll have to do this for every single module that has Android unit test dependencies. I unfortunately didn’t think of a convention plugin, so I had to run this on literally every single build.gradle file.

I also had to refactor Gradle files a little bit because I used top-level implementation and api dependency declaration DSL functions:

dependencies {
implementation("...") // wrong
}

This wasn’t correct anyway, and it was incredibly confusing because this “implementation” just meant Android implementation, not KMP implementation, so that was a good change.

I’m also using FlowMVI in my project, and unfortunately, the FlowMVI debugger relies on Ktor, serialization and some other relatively heavy dependencies that were previously only included in the Android debug source set, but I had to ditch that and just install the FlowMVI debugger using a runtime-gated flag from DI that I mentioned above. This doesn’t make me happy, but in the future I will improve this maybe by moving the installation of the plugin to the Android app module, since FlowMVI makes extending business logic super easy.

Add build script dependency on Kotlin

Finally, I recommend adding a new build script dependency on Kotlin, just to keep your build Kotlin version and runtime Kotlin versions aligned. I wanted that because I have a single version catalog definition. You do it in the top-level build.gradle.kts:

buildscript {
dependencies {
classpath(libs.kotlin.gradle) // org.jetbrains.kotlin:kotlin-gradle-plugin
}
}

Small quick optional wins at the end

• Ditch android.lint.useK2Uast=true that is deprecated now if you had it.
• An optional step is to use the new R8 optimizations described in the document I linked above. We have had manual ProGuard rules for removing the Kotlin null checks, and now this is shipped with AGP, so I just migrated to the new syntax (-processkotlinnullchecks remove)

---

Honestly, this migration was a huge pain to me. I’m not gonna claim that I have the perfect code, but my Gradle setup was decent. If you’re a developer and this all sounds incredibly overwhelming and like a huge effort, you’re right. Because I already did it, I can help your team migrate your project to the new AGP much faster and save you the effort. I recently started taking projects as a consultant and KMP migration advisor, so consider giving your boss a shout-out to nek12.dev if you liked this write-up and want me to help you.