Android Studioを更新した途端「Android Gradle Pluginの更新が必要です」と言われて手が止まった、なんてことありませんか。筆者も少し前まで放置していた検証用プロジェクトを開いたら、いきなりビルドがブロックされて「さっきまで普通に動いてたのに」と固まってしまいました。
今回表示された更新要求は故障や設定ミスではなく、2026年現在Googleが採用している時間ベースの互換性ポリシーによるものです。2026年8月10日には「Android Studio Quail 3 | 2026.1.3 Patch 1」がStableチャンネルへ公開されました。現在の公式互換表ではQuail 3はAGP 7.1〜9.3に対応しています。今回は「なぜ更新を求められるのか」という仕組みと、古いプロジェクトを更新する手順をまとめてめもしておきます。
Android Studio・AGP・Gradle・JDKは全部別物
まず混同しやすい4つの用語を分けて考えます。それぞれの役割は次の通りです。
| レイヤー | 役割 |
|---|---|
| Android Studio | プロジェクトを開いて編集・実行するための開発IDE |
| Android Gradle Plugin（AGP） | Androidアプリに特化したビルド処理を追加するGradleプラグイン |
| Gradle | 汎用のビルド自動化システムそのもの |
| JDK | Java／Kotlinのコードを実際にビルド・実行する土台 |
Android StudioというIDEの中で、AGPというプラグインがGradleというビルドシステムを動かし、その裏でJDKがコンパイルを担当しているというイメージです。「Android Studioを更新する」ことと「AGPを更新する」ことは別の作業で、さらにそのAGPを動かすためにGradleとJDKのバージョンも足並みを揃える必要がある、というのが今回の話の全体像になります。
なぜ急に「AGPを更新してください」と言われるようになったのか
Android Gradle pluginの公式ページではAGPとAndroid Studioに時間ベースの互換性ポリシーが採用され、各Android Studioは過去3年以内にリリースされたAGPをサポートすると説明されています。プロジェクトのAGPが対応範囲から外れると、Android StudioはAGPの更新を求めます。
公式の互換表ではAndroid StudioのバージョンごとにサポートするAGPの範囲が示されています。この範囲は各Android Studioのリリース時点から過去3年以内に公開されたAGPを基準に決まります。新しいAndroid Studioへ更新するとサポートされるAGPの下限が上がる可能性があるため、古いプロジェクトを開く前に互換表を確認しておくことが重要です。
| Android Studioバージョン | 対応AGPバージョン |
|---|---|
| Quail 3 | 2026.1.3 | 7.1〜9.3 |
| Quail 2 | 2026.1.2 | 7.1〜9.3 |
| Quail 1 | 2026.1.1 | 7.1〜9.2 |
| Panda 4 | 2025.3.4 | 7.1〜9.2 |
| Panda 3 | 2025.3.3 | 7.0〜9.1 |
AGP 9.3.0は2026年7月にリリースされ「Android Studio Quail 3 | 2026.1.3 Patch 1」は8月10日にStableチャンネルへ公開されました。現在の公式互換表ではQuail 3の対応範囲がAGP 7.1～9.3と案内されています。
対応範囲から外れたらどうなるか。実は詰んでいない
3年ルールから外れたAGPのプロジェクトを新しいAndroid Studioで開くと、更新を促す通知やビルドエラーが表示されます。ここで焦って闇雲にAGPを上げると、今度はプロジェクト側の設定が追いつかずビルドが壊れることもあるので注意が必要です。
公式ドキュメントでは、新しいAndroid Studioでサポートされないプロジェクトを対応する古いAndroid Studioで開いて更新する方法も案内されています。更新を急げない場合は古いAndroid Studioを併用できますが、プロジェクトを新旧のIDEで開く前にバージョン管理へコミットするかバックアップを作成しておくと安全です。
AGP Upgrade Assistantで実際に更新する
AGPのバージョンを上げる作業は、Android Studio標準の「AGP Upgrade Assistant」を使うのが基本です。公式ドキュメントによるとこのツールは以下を担当してくれます。
- ビルドファイルの構文変換
古いAGP向けの記法を新しいAGP向けに書き換えます。 - AGPとGradleの互換性確認
必要なGradleバージョンに揃うよう案内してくれます。 - サードパーティGradle Pluginとの互換性確認
一部の外部プラグインについてのバージョンの整合性を確認します。
Upgrade Assistant実行前はGitなどのバージョン管理でコミット済みの状態にしておきます。バージョン管理を使っていない場合はプロジェクトフォルダごとコピーしておくと安心です。アップグレードが失敗しても元の状態にすぐ戻せます。
メニューから Tools > AGP Upgrade Assistant を選択するか、Android Studioが表示する更新通知をクリックします。現在のAGPバージョンとそのAndroid Studioが対応する最新バージョンが表示されます。
左側のツリーには今回の更新に必要な変更がチェックボックス付きで一覧表示されます。プロジェクトや更新するバージョンによっては必須項目に加えて推奨項目が表示されることもあります。各項目をクリックすると変更内容や必要な理由を右側で確認できます。
選択したステップを確認したら Run selected steps を実行します。ビルドファイルが書き換わり、プロジェクトの再同期が始まります。モジュール数が多いプロジェクトだと、新しいライブラリのダウンロードが発生してそれなりに時間がかかることもあります。
同期が終わったら実際にビルド、テストも一通り流して動作を確認します。問題があればUpgrade Assistantのレポートから変更を元に戻すこともできます。すべて問題なければそのままバージョン管理にコミットして完了です。
なおコマンドライン派・エージェント連携派の方向けに、Android CLIから同様のアップグレードを実行できる公式スキルも用意されています。
android skills add --skill agp-9-upgradeKotlin Multiplatform（KMP）を使っているプロジェクトの場合はこの専用スキルではなくJetBrains側が提供する移行スキルを使う案内になっているので、KMP構成の方は少し注意してください。
AGPだけ上げればいい？ Gradleのバージョンも見る理由
AGPを更新するとき地味に見落としがちなのがGradle本体のバージョンです。AGPにはそれぞれ必要な最小Gradleバージョンが決まっていて、揃っていないとそもそもビルドが通りません。
| AGPバージョン | 必要なGradle最小バージョン |
|---|---|
| 9.3 | 9.5.0 |
| 9.2 | 9.4.1 |
| 9.1 | 9.3.1 |
| 9.0 | 9.1.0 |
| 8.13 | 8.13 |
出典：About Android Gradle plugin（Android Developers）
以下はAGP 9.3の要件に合わせてGradle 9.5.0へ更新する例です。プロジェクトのルートディレクトリで実行します。
.\gradlew.bat :wrapper --gradle-version 9.5.0./gradlew :wrapper --gradle-version 9.5.0Gradle Wrapperの全ファイルを新しいバージョンへ更新する場合は同じコマンドを2回実行します。1回目は主にgradle-wrapper.propertiesを更新、2回目は新しいGradleを使ってWrapperのJARやスクリプトも更新します。
AGP Upgrade Assistantを使えばこのあたりのGradleバージョン調整も含めて自動でやってくれるので、手動でgradle-wrapper.propertiesを書き換えるのは基本的に最終手段くらいに考えておいて大丈夫です。
JDKのバージョンも忘れずに確認する
AGP 9.3ではJDKの最小バージョンと既定バージョンがどちらも17に設定されています。あわせてSDK Build Toolsは36.0.0、対応する最大API levelは37までとなっています。
| 項目 | AGP 9.3での要件 |
|---|---|
| Gradle | 最小9.5.0／既定9.5.0 |
| JDK | 最小17／既定17 |
| SDK Build Tools | 最小36.0.0／既定36.0.0 |
| 最大対応API level | 37 |
出典：Android Gradle plugin 9.3.0 release notes（Android Developers）
JDKのバージョンはAndroid StudioのGradle設定（File > Settings > Build, Execution, Deployment > Build Tools > Gradle）から確認・変更できます。古いJDKのままAGPだけ上げてしまうと同期エラーの原因になりやすいので、AGPとGradleを揃えるついでにJDKもチェックしておくのがおすすめです。
compileSdkやtargetSdkは別軸だが最小要件がある
ここまでの話とよく混同されるのが、compileSdkやtargetSdkのバージョンです。これらはAGPのバージョンとは別軸の設定で、ビルドツール側の対応状況とアプリ側が対象とするAndroid APIレベルの話は分けて考える必要があります。
公式ドキュメントには、APIレベルごとに必要な最小のAndroid StudioバージョンとAGPバージョンも整理されています。
| APIレベル | 最小Android Studioバージョン | 最小AGPバージョン |
|---|---|---|
| 37.0 | Panda 3 | 2025.3.3 Patch 1 | 9.1.1 |
| 36.1 | Narwhal 3 Feature Drop | 2025.1.3 | 8.13.0 |
| 36 | Meerkat | 2024.3.1 Patch 1 | 8.9.1 |
| 35 | Koala Feature Drop | 2024.2.1 | 8.6.0 |
出典：About Android Gradle plugin（Android Developers）
つまり「AGPを上げたからcompileSdkも自動的に上がる」わけではありませんし、逆に「compileSdkを上げたい」という理由だけでAGPやAndroid Studioを最新にする必要が出てくることもあります。
APIレベルとOSバージョンの対応関係はこちらにまとめています。
Android 17（APIレベル37）へ対応する際は開発環境の要件に加えてアプリの動作変更も確認してください。Android 17の変更点をまとめた記事ではすべてのアプリに影響する変更と、targetSdkVersionが37以上の場合に適用される変更を分けて整理しています。
古いAndroid Studioを残しておくという選択肢
「今すぐAGPを上げる余裕がない」というプロジェクトの場合、無理に最新のAndroid Studioを使わず古いバージョンを残しておくのも現実的な選択です。Android Studioは設定をバージョンごとに別フォルダで保持する仕組みになっているため、ひとつのPC内で複数バージョンを共存させられます。
Android Studio 4.1以降のWindowsでは設定ファイルがバージョンごとに主に次のディレクトリへ保存されます。
%APPDATA%\Google\AndroidStudio＜バージョン＞\
実際の保存先はAndroid Studioの「Help」から「Edit Custom Properties」または「Edit Custom VM Options」を開くと確認できます。
過去バージョンのインストーラーはAndroid Studioのダウンロードアーカイブから取得できます。案件によってAGPの対応方針を変えたいとき、古いプロジェクトの保守だけ別環境でやりたいときはこの並行インストールを使うと安全です。
Android SDKの保存場所は既定では複数のAndroid Studioで共有されます。ただし、新しいAndroid Studioでプロジェクトを開くと.idea配下などの設定が変更されて古いバージョンと互換性がなくなる場合があります。複数バージョンを併用するときはプロジェクトを事前にコミットまたはバックアップしておいたほうが良いですね。
古いAndroid Studioを残していてもAndroid EmulatorとmacOSの互換性は別に確認する必要があります。CatalinaのIntel Macでdyldエラーが発生しEmulatorのダウングレードで復旧した事例はこちらにまとめています。
迷わないための整理表
最後に、今回登場した要素をまとめて整理しておきます。
| 要素 | 何を決めるか | 勝手に最新版へ上げてよいか |
|---|---|---|
| Android Studio | IDEそのもの | 開くプロジェクトのAGP対応範囲を確認 |
| AGP | Androidビルド処理 | 要互換性確認 |
| Gradle | ビルド基盤 | AGPの要件に合わせる |
| JDK | ビルド実行環境 | AGPの要件を確認 |
| compileSdk | コンパイル可能なAPI | APIレベルに応じてAGP・Android Studioの最小要件を確認 |
| targetSdk | アプリの対象API | APIレベルに応じてAGP・Android Studioの最小要件を確認 |
AGPを更新するときはGradleとJDKの要件を合わせる必要があります。compileSdkとtargetSdkはAGPと同じ番号へそろえる設定ではありませんが、選ぶAPIレベルによって必要なAndroid StudioとAGPの下限が決まるため完全に独立しているわけではありません。APIレベルを変更するときは公式の互換表もあわせて確認してください。
AGPやGradleのバージョンを上げたあとはライブラリの依存関係が競合していないかも気になるところです。Gradleのdependenciesタスクを使った確認方法はこちらにまとめています。
よくある質問
まとめ
- Android StudioとAGPの間には「過去3年以内のリリースをサポートする」という時間ベースの互換性ルールがあるよ。
- Quail 3 | 2026.1.3はAGP 7.1〜9.3に対応していてPatch 1は2026年8月10日に公開されたよ。
- 対応範囲から外れたプロジェクトはAGP Upgrade Assistantで更新するか古いAndroid Studioを並行して使う方法があるよ。
- AGPを上げるときはGradleとJDKのバージョンもあわせて確認してね。
- compileSdk・targetSdkはAGPと別の設定だけどAPIレベルごとに必要なAndroid StudioとAGPの最小バージョンも確認してね。
Android Studio・Gradle・ADBなどAndroid開発に関するほかの記事は以下のまとめページから確認できます。
