Android Gradle プラグインのリリースノート

JCenter リポジトリは、2021 年 3 月 31 日に読み取り専用になりました。詳細については、JCenter サービスの更新をご覧ください。

Android Studio ビルドシステムは Gradle をベースにしており、Android Gradle プラグインは Android アプリのビルドに特化した機能を追加します。Android プラグインは通常、Android Studio に同期してアップデートされますが、プラグイン（および他の Gradle システム）は Android Studio から独立して実行でき、個別にアップデートできます。

このページでは、Gradle ツールを最新の状態に保つ方法と、最近のアップデートの内容について説明します。過去の Android Gradle プラグイン バージョンのリリースノートについては、過去のリリースノートをご覧ください。

Android Gradle プラグインの今後予定されている重要な変更の概要については、 Android Gradle プラグインのロードマップをご覧ください。

Gradle で Android ビルドを設定する方法の詳細については、下記のページをご覧ください。

Gradle ビルドシステムの詳細については、Gradle のユーザーガイドをご覧ください。

Android Gradle プラグインのアップデート

Android Studio をアップデートすると、Android Gradle プラグインを利用可能な最新バージョンに自動的にアップデートするように促すメッセージが表示されることがあります。アップデートに同意するか、プロジェクトのビルド要件に基づいて手動でバージョンを指定するかを選択できます。

プラグインのバージョンは、Android Studio の [File] > [Project Structure] > [Project] メニュー、または最上位の build.gradle.kts ファイルで指定できます。プラグインのバージョンは、その Android Studio プロジェクトでビルドされたすべてのモジュールに適用されます。次の例では、build.gradle.kts ファイルからプラグインをバージョン 8.1.0 に設定しています。

Kotlin

plugins {
    id("com.android.application") version "8.1.0" apply false
    id("com.android.library") version "8.1.0" apply false
    id("org.jetbrains.kotlin.android") version "1.5.31" apply false
}

Groovy

plugins {
    id 'com.android.application' version '8.1.0' apply false
    id 'com.android.library' version '8.1.0' apply false
    id 'org.jetbrains.kotlin.android' version '1.5.31' apply false
}

注意: バージョン番号には、'com.android.tools.build:gradle:2.+' などの動的な依存関係を使用しないでください。予期しないバージョンのアップデートが起こり、バージョンの相違を解決するのが難しくなる可能性があるためです。

指定されたプラグイン バージョンがダウンロードされていない場合、Gradle は次回プロジェクトをビルドするときにダウンロードします。または、Android Studio のメニューバーで [File] > [Sync Project with Gradle Files] をクリックします。

Gradle のアップデート

Android Studio をアップデートすると、Gradle を利用可能な最新バージョンにアップデートするように促すメッセージが表示されることもあります。アップデートに同意するか、プロジェクトのビルド要件に基づいて手動でバージョンを指定するかを選択できます。

次の表に、Android Gradle プラグインの各バージョンに必要な Gradle のバージョンを示します。最高のパフォーマンスを得るには、Gradle とプラグインの両方について、最新バージョンを使用してください。

プラグインのバージョン必要最小限の Gradle バージョン
8.38.3
8.28.2
8.18.0
8.08.0
7.47.5

古いバージョン

プラグインのバージョン必要な Gradle のバージョン
7.37.4
7.27.3.3
7.17.2
7.07.0
4.2.0 以降6.7.1
4.1.0 以降6.5 以降
4.0.0 以降6.1.1 以降
3.6.0 - 3.6.45.6.4 以降
3.5.0 - 3.5.45.4.1 以降
3.4.0 - 3.4.35.1.1 以降
3.3.0 - 3.3.34.10.1 以降
3.2.0 - 3.2.14.6 以降
3.1.0 以降4.4 以降
3.0.0 以降4.1 以降
2.3.0 以降3.3 以降
2.1.3 - 2.2.32.14.1 - 3.5
2.0.0 - 2.1.22.10 - 2.13
1.5.02.2.1 - 2.13
1.2.0 - 1.3.12.2.1 - 2.9
1.0.0 - 1.1.32.2.1 - 2.3

Gradle のバージョンを指定するには、Android Studio の [File] > [Project Structure] > [Project] メニューで、またはコマンドラインを使用して Gradle のバージョンを更新します。 おすすめの方法は、Gradle ラッパー コマンドライン ツールを使用して、gradlew スクリプトを更新する方法です。次の例では、Gradle ラッパーを使用して Gradle のバージョンを 8.1 に設定しています。なお、このコマンドを 2 回実行して、Gradle と Gradle ラッパー自体の両方をアップグレードする必要があります（詳細については、Gradle ラッパーのアップグレードをご覧ください）。

gradle wrapper --gradle-version 8.1

ただし、AGP をアップデートしたばかりで、現在の Gradle バージョンに準拠しなくなった場合などは、失敗することがあります。この場合は、gradle/wrapper/gradle-wrapper.properties ファイルで Gradle ディストリビューションの参照を編集する必要があります。次の例では、gradle-wrapper.properties ファイルで Gradle のバージョンを 8.1 に設定しています。 

...
distributionUrl = https\://services.gradle.org/distributions/gradle-8.1-bin.zip
...

Android Gradle プラグインと Android Studio の互換性

Android Studio ビルドシステムは Gradle をベースにしており、Android Gradle プラグイン（AGP）は Android アプリのビルドに役立つ複数の機能を追加します。次の表に、Android Studio の各バージョンに必要な AGP のバージョンを示します。

Android Studio バージョン 必要な AGP バージョン
Iguana | 2023.2.1 3.2-8.3
Hedgehog | 2023.1.1 3.2-8.2
Giraffe | 2022.3.1 3.2-8.1
Flamingo | 2022.2.1 3.2-8.0
Electric Eel | 2022.1.1 3.2-7.4

古いバージョン

Android Studio バージョン 必要な AGP バージョン
Dolphin | 2021.3.1 3.2-7.3
Chipmunk | 2021.2.1 3.2-7.2
Bumblebee | 2021.1.1 3.2-7.1
Arctic Fox | 2020.3.1 3.1-7.0

Android Gradle プラグインの新機能については、Android Gradle プラグインのリリースノートをご覧ください。

Android API レベルに対応するツールの最小バージョン

特定の API レベルをサポートする Android Studio と AGP の最小バージョンがあります。プロジェクトの targetSdk または compileSdk で必要とされるバージョンよりも低いバージョンの Android Studio または AGP を使用すると、予期しない問題が発生する可能性があります。Android OS のプレビュー バージョンをターゲットとするプロジェクトを扱うには、Android Studio と AGP の最新のプレビュー版を使用することをおすすめします。Android Studio のプレビュー バージョンを安定版とともにインストールできます。

Android Studio と AGP の最小バージョンは次のとおりです。

API レベル Android Studio の最小バージョン AGP の最小バージョン
34 Hedgehog | 2023.1.1 8.1.1
33 Flamingo | 2022.2.1 7.2

バージョニングの変更（2020 年 11 月）

基盤となる Gradle ビルドツールのバージョン番号により近い番号で管理できるよう、Android Gradle プラグイン（AGP）のバージョン番号の付け方を変更します。

主な変更点は次のとおりです。

  • AGP はセマンティック バージョニングを使用するようになり、互換性のない変更はメジャー リリースとして扱われます。

  • Gradle のメジャー リリースに合わせて、AGP のメジャー バージョンを年 1 回リリースします。

  • AGP 4.2 の次のリリースはバージョン 7.0 となり、Gradle のバージョンも 7.x にアップグレードする必要があります。AGP のメジャー リリースのたびに、基盤となる Gradle ツールのメジャー バージョン アップグレードが必要になります。

  • API はメジャー リリースの約 1 年前からサポート終了となり、それと同時に代替機能が利用可能になります。サポートが終了した API は、約 1 年後のメジャー アップデート時に削除されます。

8.1.0（2023 年 7 月）

Android Gradle プラグイン 8.1.0 はメジャー リリースで、さまざまな新機能や改善措置が組み込まれています。

互換性

最小バージョン デフォルトのバージョン Notes
Gradle 8.0 8.0 詳細については、Gradle のアップデートをご覧ください。
SDK Build Tools 33.0.1 33.0.1 SDK Build Tools をインストールまたは設定します。
NDK なし 25.1.8937393 別のバージョンの NDK をインストールまたは設定します。
JDK 17 17 詳細については、JDK バージョンの設定をご覧ください。

Kotlin DSL がビルド構成のデフォルト

新しいプロジェクトでは、ビルド構成にデフォルトで Kotlin DSL（build.gradle.kts）が使用されるようになりました。これにより、構文のハイライト表示、コード補完、宣言への移動など、Groovy DSL（build.gradle）よりも優れた編集作業が実現します。ビルド構成に AGP 8.1 と Kotlin DSL を使用している場合は、Gradle 8.1 を使用することをおすすめします。詳細については、Kotlin DSL 移行ガイドをご覧ください。

アプリ別の言語の自動サポート

Android Studio Giraffe Canary 7 と AGP 8.1.0-alpha07 以降では、アプリ別の言語設定をサポートするようにアプリを自動的に構成できます。Android Gradle プラグインはプロジェクト リソースに基づいて LocaleConfig ファイルを生成し、その参照を最終的なマニフェスト ファイルに追加するため、手動で行う必要がなくなります。AGP は、アプリ モジュールの res フォルダ内のリソースとライブラリ モジュールの依存関係を使用して、LocaleConfig ファイルに含めるロケールを決定します。

自動のアプリ別の言語機能は、Android 13（API レベル 33）以降を実行するアプリをサポートしています。この機能を使用するには、compileSdkVersion を 33 以上に設定する必要があります。以前のバージョンの Android のアプリ別の言語設定を設定するには、API とアプリ内言語選択ツールを使用する必要があります。

アプリ別の言語の自動サポートを有効にするには、デフォルトの言語 / 地域を指定します。

  1. アプリ モジュールの res フォルダに、resources.properties という名前の新しいファイルを作成します。

  2. resources.properties ファイルで、unqualifiedResLocale ラベルを使用してデフォルトの言語 / 地域を設定します。ロケール名を形成するには、言語コードをスクリプトや地域コード（省略可）と組み合わせ、それぞれをダッシュで区切ります。

    • 言語: 2 文字または 3 文字の ISO 639-1 コードを使用します。
    • スクリプト（省略可）: ISO 15924 コードを使用します。
    • 地域（省略可）: 2 文字の ISO 3166-1-alpha-2 コードまたは 3 桁の UN_M.49 コードを使用します。

    たとえば、デフォルトのロケールがアメリカ英語である場合は次のとおりです。

        unqualifiedResLocale=en-US

AGP は、このデフォルトのロケールと、res フォルダの values-* ディレクトリを使用して指定した代替ロケールを、自動生成された LocaleConfig ファイルに追加します。

アプリ別の言語の自動サポートはデフォルトでオフになっています。この機能を有効にするには、モジュール レベルの build.gradle.kts ファイル（Groovy を使用している場合は build.gradle ファイル）の androidResources {} ブロックで generateLocaleConfig 設定を使用します。

Kotlin

android {
  androidResources {
    generateLocaleConfig = true
  }
}

Groovy

android {
  androidResources {
    generateLocaleConfig true
  }
}

Android lint に JVM 17 をターゲットとするバイトコードが含まれている

AGP 8.1.0-alpha04 以降、Android lint には、JVM 17 をターゲットとするバイトコードが含まれています。カスタム lint チェックを作成する場合は、JDK 17 以降でコンパイルし、Kotlin コンパイラ オプションで jvmTarget = '17' を指定する必要があります。

lint ツールの詳細については、lint チェックでコードを改善するをご覧ください。

ネイティブ ライブラリの圧縮設定を DSL に移動しました

AGP 8.1.0-alpha10 以降では、マニフェストの代わりに DSL を使用してネイティブ ライブラリ圧縮を構成しないと、警告が表示されます。次のガイダンスでは、DSL を使用するように構成を更新する方法について説明します。これらの更新に関してサポートを受けるには、AGP Upgrade Assistant（[Tools] > [AGP Upgrade Assistant]）を使用してください。

非圧縮ネイティブ ライブラリを使用するには、マニフェストから android::extractNativeLibs 属性を削除し、モジュール レベルの build.gradle.kts ファイル（Groovy を使用している場合は build.gradle ファイル）に次のコードを追加します。

Kotlin

android {
  packagingOptions {
    jniLibs {
      useLegacyPackaging = false
    }
  }
}

Groovy

android {
  packagingOptions {
    jniLibs {
      useLegacyPackaging false
    }
  }
}

試験運用版ビルドフラグ

これらは、AGP 8.1 で利用可能なビルドを設定するための試験運用版のフラグです。

フラグ 追加先 デフォルト値 Notes
android.experimental.useDefaultDebugSigningConfigForProfileableBuildtypes AGP 8.0 false 署名設定を指定せずにこの機能を有効にすると、プロファイル可能またはデバッグ可能なビルドの実行時に、AGP はデフォルトのデバッグ署名設定を使用します。このフラグはデフォルトで無効になっており、ビルド作成者には特定のプロファイリング署名設定を宣言することが推奨されます。
android.experimental.library.desugarAndroidTest AGP 8.0 false このフラグにより、ライブラリ ビルダーは、lint チェックなどを通じて、生成される AAR に影響を与えることなく、テスト APK のコアライブラリの脱糖を有効にできます。 今後、Variant API でこの動作をサポートする予定です。
android.experimental.testOptions.managedDevices.customDevice AGP 8.0 false 有効にした場合、Gradle で管理されているデバイスでは、プラグインで提供可能なユーザー定義のカスタム デバイスタイプを使用できます。Firebase Test Lab プラグインを使用する場合は、このフラグを有効にする必要があります。
android.lint.printStackTrace AGP 8.0 false 有効にすると、Android lint はクラッシュするとスタック トレースを出力します。このフラグは、LINT_PRINT_STACKTRACE 環境変数と同じ機能を持ちます。
android.experimental.testOptions.managedDevices.maxConcurrentDevices AGP 8.0 なし ある時点で同時にアクティブにする Gradle で管理されているデバイス（AVD）の最大数を指定します。値が 0 または負の場合、デバイスの最大数はありません。
android.experimental.testOptions.installApkTimeout AGP 8.0 なし APK のインストールのタイムアウト時間（秒）。値が 0 または負の場合は、UTP によってデフォルト値に設定されます。