Android Gradle プラグインの DSL / API の移行スケジュール

Android Gradle プラグイン（AGP）は、Android アプリでサポートされているビルドシステムであり、さまざまなタイプのソースをコンパイルして、実際の Android デバイスまたはエミュレータ上で実行可能なアプリにまとめてリンクできます。

以下のセクションでは、AGP の DSL と API の予定されている進化について説明します。 安定版リリースで新しい API が導入されると、古い API は非推奨としてマークされます。非推奨の API は、次の安定版リリースでは利用できなくなります。以降のセクションでは、AGP の各メジャー リリースで予定されている変更点について説明します。

AGP API の非推奨や削除の詳細なログについては、AGP API の更新をご覧ください。

AGP 10.0（2026 年後半）

Android Gradle プラグイン 10.0 の API の変更と最新化

AGP 10.0 では、完全に遅延評価される構成キャッシュ互換のビルドモデルへの移行が完了します。このリリースは、レガシーの非遅延評価 API をより安全でパフォーマンスの高いアーキテクチャに置き換えるための長年の取り組みの集大成です。

遅延評価ビルドモデルを使用する理由

レガシーの非遅延評価ビルドモデルでは、Gradle はすべてのプロジェクト モジュールで、同期またはビルドの呼び出しごとにオブジェクトを即時評価し、バリアントデータをクエリして、タスクを構成します。この即時評価では、実行されていないバリアントとタスクで CPU 時間とメモリが浪費され、複雑なビルドスクリプトで評価順序の競合が発生します。

遅延評価プロバイダ (Provider<T>)と最新の Variant API (androidComponents {})を使用して完全に遅延評価されるビルドモデルに移行することで、プロパティ とタスクの配線は、アクティブなビルド実行グラフで必要な場合にのみ、オンデマンドで遅延評価されます。

このリリースで削除されるレガシー API は、この最新のアーキテクチャと根本的に互換性がありませんでした。これらの API を削除することで、AGP は Gradle 構成キャッシュとプロジェクト分離を完全にサポートできるようになり、Android Studio でのビルド速度と同期時間が大幅に向上します。

アーキテクチャの主な違い

レガシーの BaseVariant API（applicationVariants.all {}）は即時評価され、タスク中心でした。構成フェーズで Gradle タスクと内部構成に直接アクセスできるため、最新の Gradle パフォーマンス機能が本質的に損なわれていました。

新しい Variant API（androidComponents {}）は遅延評価され、アーティファクト中心です。Gradle の Property API を広範に使用し、 Task と TaskProvider への参照をすべて削除します。これにより、基盤となるタスク自体ではなく、入力と 出力（Variant.artifacts）をクリーンに操作できます。

削除および置き換えられるもの

レガシーの DSL と古い Variant API で使用されていた以前のインターフェースとクラスはすべて削除されます。ビルドスクリプトとカスタム プラグインを準備するには、サポート終了となる次の API とフラグから移行します。

すべての置き換え DSL と Variant API（androidComponents {}） のインターフェースとクラスにアクセスするには、カスタム Gradle プラグインまたはビルドロジックを開発するときに常に gradle-api アーティファクトを使用します。

移行手順

AGP 10.0 へのアップグレードをスムーズかつ予測可能にするには、次の移行方法に従ってください。

1. AGP Upgrade Assistant を実行する: 10.0 に直接アップグレードする前に、Android Studio で公式の AGP Upgrade Assistant（Tools > AGP Upgrade Assistant）を実行します。これにより、一般的な DSL とビルドスクリプトの移行が自動化され、既存のビルド動作を維持できます。
2. Android Studio でエージェント モードのスキルを使用する: AI アップグレード スキル（Android スキル リポジトリで利用可能な AGP アップグレード スキルなど）を活用して、Android Studio 内の複雑なビルドロジックと DSL の移行を自動化して簡素化します。
3. まず AGP 9.x で非推奨の警告を修正する: プロジェクトを最新の AGP 9.x リリースにアップグレードし、既存の非推奨の警告をすべて解決します。プロジェクトが 9.x で警告なしで動作し、android.newDsl=false または android.builtInKotlin=false に依存していない場合は、10.0 への移行がスムーズに行えます。
4. サードパーティの Gradle プラグインを監査する: サードパーティのプラグインが AGP 10.0 互換バージョンにアップグレードされていることを確認します。レガシー拡張機能タイプに依存しているプラグインは、ClassCastException: ... cannot be cast to class BaseExtension などのビルドエラーを引き起こします。
5. 公式の移行レシピを使用する: 複雑な実際の移行 例と並列比較については、公式の gradle-recipes GitHub リポジトリをご覧ください。

レガシー バリアントの即時評価クエリから androidComponents {} を使用したバリアントの遅延評価構成への移行方法を比較した例を以下に示します。

前: レガシー Variant API（AGP 10.0 で削除）

// Eager evaluation using the legacy Variant API
android {
    applicationVariants.all { variant ->
        if (variant.buildType.name == "release") {
            // Eagerly queries and modifies properties during evaluation
        }
    }
}

後: 最新の Variant API（androidComponents {}）

// Lazy, Configuration Cache compatible Variant API
androidComponents {
    onVariants(selector().withBuildType("release")) { variant ->
        // Safely and lazily configures properties
    }
}

AGP 9.x で AGP 10.0 の動作をテストする方法

AGP 10.0 のリリースを待たずに、ビルド動作のテストと互換性の検証を開始できます。AGP 9.x リリースで実行している場合は、gradle.properties でオプトアウトが無効になっていて、次の厳格な動作フラグが設定されていることを確認することで、AGP 10.0 の動作を明示的に適用できます。

# Enforce modern DSL and Variant API interfaces exclusively
android.newDsl=true

# Enforce built-in Kotlin support without optional opt-out
android.builtInKotlin=true

android.newDsl=true と android.builtInKotlin=true を適用することで、カスタム ビルドロジックとサードパーティのプラグインが AGP 10.0 の厳格な API 要件と完全に互換性があることを確認できます。

移行中のサブプロジェクトの選択的なオプトアウト

最新の動作をテストするために、プロジェクト全体で android.newDsl=true を有効にするが、特定のサブプロジェクトの移行に時間がかかる場合は、AGP 9.4.0-alpha04 以降で個々のモジュールを選択的にオプトアウトできます。 gradle.properties に android.newDsl.optOut を追加して、プロジェクト パスを指定します。

# Enable modern DSL globally across the build
android.newDsl=true

# Selectively opt out specific sub-projects that still require legacy DSL APIs
android.newDsl.optOut=:lib

モジュールごとに組み込みの Kotlin を選択的に無効にする

プロジェクト全体で組み込みの Kotlin を有効にする（android.builtInKotlin=true）が、特定のサブプロジェクトを kotlin-android から移行する（または Kotlin コードのないモジュールの場合）に時間がかかる場合は、プロジェクト レベルではなく DSL レベルでこれらのモジュールを構成します。モジュールのビルドファイル内で enableKotlin = false を設定します。

android {
    enableKotlin = false
}

フィードバックとバグ報告のワークフロー

Google は、新しい Variant API が必要なユースケースをサポートしていることを確認したいと考えています。新しい Variant API でユースケースに対応できない古い API からの移行で問題が発生した場合は、次の手順でフィードバックをお送りください。

1. 既存の項目を確認する: まず、AGP 10.0 Variant API のグローバル トラッキング バグを確認して、移行の妨げとなる問題が すでに報告されているかどうかを確認し、問題に +1 を付けます。
2. 不足している API を報告する: ユースケースが固有の場合は、特定の Variant API テンプレートを使用して新しい機能 リクエストを提出してください。Google が調査してサポートいたします。

（未定）非公開の内部 AGP クラスへのアクセス権が削除されます

gradle アーティファクトへの依存関係によって、すべての内部 クラスが非表示になり、gradle-api アーティファクトで使用できるインターフェースとクラスにのみコンパイル アクセス権が付与されます。これは プラグインのコンパイルに影響します。

内部クラスにアクセスするために、手動で依存関係を追加することはできません。

AGP 9.0（2026 年 1 月）

新しい Variant API が安定版となり、古い API は非推奨となります

4.1 と 4.2 では準備中であった Variant API が 安定し、gradle-api アーティファクトに配置されます。古い Variant API で使用されていた以前のインターフェースとクラスは非推奨となり、使用するには明示的なオプトインが必要です。

新しい DSL インターフェースが安定版となり、古い DSL インターフェースは非推奨となります

DSL インターフェースは 4.1、4.2、 7.0 では準備中でしたが、安定し、gradle-api アーティファクトに配置されます。DSL で使用していた以前の インターフェースとクラスは非推奨となり、使用するには 明示的なオプトインが必要です。

非公開の内部 AGP クラスには引き続きアクセス可能

他のアーティファクトにある AGP の非公開の内部クラスには、ビルドファイルとプラグインのコンパイル中に引き続きアクセスできますが、常に破壊的に変更される可能性があるため、使用することはおすすめしません。