AGP 9 Upgrade Workflow
Priority: P1 (HIGH)
Step-by-step workflow for upgrading an Android project to AGP 9.
Prerequisites
- Check current AGP version. If below 8.x, recommend running the AGP Upgrade Assistant in Android Studio first.
- Do NOT use this skill for Kotlin Multiplatform (KMP) projects.
- Verify Gradle, JDK, and Kotlin version compatibility with AGP 9 release notes.
Step 1: Update dependencies
- If KSP (
com.google.devtools.ksp) is used, ensure version 2.3.6+. - If Hilt is used, ensure version 2.59.2+.
- Update AGP to the latest stable 9.x version in the project's build files.
Step 2: Migrate to built-in Kotlin
AGP 9 includes built-in Kotlin support — the org.jetbrains.kotlin.android plugin is no longer needed.
See migration guide for detailed steps.
Step 3: Migrate to the new AGP DSL
AGP 9 introduces a new DSL for android {} blocks. Key changes include namespace handling, build type configuration, and source set declarations.
See DSL migration for before/after examples.
Step 4: Migrate kapt to KSP or legacy-kapt
If the project uses kapt:
- Prefer migrating to KSP where annotation processors support it (Room, Hilt, Moshi).
- For processors without KSP support, use
legacy-kaptas a bridge.
Step 5: Update BuildConfig
If any module uses custom BuildConfig fields, update to the new AGP 9 syntax.
Step 6: Clean up gradle.properties
Remove these flags after migration:
android.builtInKotlinandroid.newDslandroid.uniquePackageNamesandroid.enableAppCompileTimeRClass
Guidelines
- Never write or run Python scripts for build migration.
- Never add
android.disallowKotlinSourceSets=falsetogradle.properties. - Do not run
cleantask when verifying — it wastes time.
Verification
./gradlew helpsucceeds../gradlew build --dry-runsucceeds.- Gradle IDE sync succeeds.

