AGP 9で必要になったKMP用プラグインの置き換え

Feb 2, 2026

2025年末から2026年の初めにかけて、Kotlin 2.3とAGP (Android Gradle Plugin) 9.0 のリリースがあり、KMPアプリケーションとライブラリのプロジェクト構成の更新が必要になりました。 Kotlin側の変更とAGP側の変更が違いに関連しており、移行の際に必要になるドキュメントが分散しているなど状況の把握に苦労しました。

そこでこの記事では、時系列に沿った変更内容と、それに伴って必要な作業の概要をまとめます。具体的な手順はKotlinとAndroidの公式ドキュメントに記載されているので、ここで改めて詳細に書くことはしませんが、ドキュメントへのリンクをまとめておくので、移行作業のエントリーポイントになればと思います。

登場するプラグイン

この記事に登場するGradleプラグインは以下の4つです。名前が似ていてややこしいので、最初に整理しておきます。

KMPプラグイン (org.jetbrains.kotlin.multiplatform)
Androidアプリケーションプラグイン (com.android.application)
Androidライブラリプラグイン (com.android.library)
KMP用Androidライブラリプラグイン (com.android.kotlin.multiplatform.library)

1はKMPモジュールの開発に必須のプラグインで、JetBrainsが提供しており、Kotlinのバージョンに紐づいています。 2〜4はGoogleのAndroidチームが提供していて、AGPのバージョンに紐づいています。 1〜3は以前から利用されており、4は新しく提供されるようになったプラグインです。

これまでの構成

まずはKotlin 2.2以前、およびAGP 8以前の状況を確認します。

KMPアプリケーションモジュールにAndroidターゲットを追加するには、KMPプラグインとAndroidアプリケーションプラグインを組み合わせて利用していました。 KMPライブラリモジュールも同様に、KMPプラグインとAndroidライブラリプラグインを組み合わせて利用していました。

ただし、これは暫定的な措置だったとのことで、Kotlin 2.3およびAGP 9でこれらの関係が整理されることになります。

Kotlin 2.3の変更

2025年12月に、Kotlin 2.3.0がリリースされました。

Kotlin 2.3以降では、KMPライブラリモジュールにAndroidターゲットを追加するために、KMP用Androidライブラリプラグイン（com.android.kotlin.multiplatform.library）が利用できるようになりました。これはAndroidライブラリプラグイン（com.android.library）を置き換えるものになります。ただし、この時点では移行は必須ではありませんでした。

AGP 9の変更

そして2026年1月に、AGP 9.0.0がリリースされました。

このリリースで、AndroidアプリケーションプラグインとAndroidライブラリプラグインが、KMPライブラリとの互換性を失います。 KMPライブラリモジュールでは、AndroidライブラリプラグインからKMP用Androidライブラリプラグインへの置き換えが必須になりました。

KMPアプリケーションモジュールでは、これまではKMPプラグインとAndroidアプリケーションプラグインを組み合わせていました。小さなKMPアプリプロジェクトの場合は、単一のアプリケーションモジュールにAndroid用のエントリーポイント（AndroidManifest.xmlやMainActivityなど）とKMPのプラットフォーム共通コードを同居させていました。 Android StudioやIntelliJ IDEAが生成するKMPプロジェクトのテンプレートもこの構成です。

1つのモジュールにKMPプラグインとAndroidアプリケーションプラグインが同居

AGP 9からはこれらを同じモジュールで利用できなくなりますが、KMP用のAndroidアプリケーションプラグインは提供されていません。そこで、Androidのエントリーポイントを独立したモジュールに切り出し、プラットフォーム共通コードはライブラリモジュールとして構成する必要があります。

なお、AGP 9では、built-in kotlinオプションを無効にすれば従来の構成で利用できますが、AGP 10ではこのオプションも利用できなくなるとのことです。

プロジェクトのディレクトリ構成

現時点でIDEが生成するプロジェクトテンプレートは、AGP 9に対応していません。

IDEでKMPプロジェクトを作成すると、composeAppというプラットフォーム共通モジュールが作られます。このディレクトリにはAndroid、Desktop、Webのエントリーポイントが配置してあります。そして、iOSのみ別のディレクトリになっています。個人的にはiOSだけ別ディレクトリになっていることに気持ち悪さがありましたが、わざわざ作り替えるのも面倒だなあという気持ちでした。

ですが今回の変更により、iOSに加えてAndroidも独立したディレクトリが必要になりました。こうなると、DesktopとWebのエントリーポイントも独立したモジュールに切り出して、それぞれのプラットフォームごとに独立したディレクトリを用意する方が統一感があって良いと思います。

KMPのチュートリアルに使われているサンプルのリポジトリでも、このディレクトリ構成に置き換える動きがみられます。 mainブランチが従来の構成、agp-9-mandaroty-changesブランチがAndroidアプリだけを独立させた構成、new-project-structureブランチがDesktopとWebも独立させた構成になっています。いずれIDEが生成するテンプレートもこの構成になるのではないかと予想しています。

AGP 9のサポート状況は？

KMPプラグイン 2.3.0は、AGP 9をサポートしていません。とはいえ、上記のような対応を一通り行えば特に問題なく動いていそうです。移行ガイドも用意されています。 Compose multiplatformも1.10.0でAGP 9をサポートしました。

とはいえこちらの移行ガイドによるといろいろ大変なことも多そうですね。。