The Android Studio build system is based on Gradle, and the Android Gradle plugin adds several features that are specific to build Android apps. Although the Android plugin is typically updated in lock-step with Android Studio, the plugin (and the rest of the Gradle system) can run independent of Android Studio and be updated separately.
This page explains how to keep your Gradle tools up to date and what's in the recent updates. For the release notes for past Android Gradle plugin versions, see past release notes.
For a high-level summary of upcoming breaking changes in the Android Gradle plugin, see the Android Gradle plugin roadmap.
For details about how to configure your Android builds with Gradle, see the following pages:
- Configure your build
- Android Gradle plugin DSL reference
- Gradle DSL reference
- Gradle performance user guide
For more information about the Gradle build system, see the Gradle user guide.
Update the Android Gradle plugin
When you update Android Studio, you may receive a prompt to automatically update the Android Gradle plugin to the latest available version. You can choose to accept the update or manually specify a version based on your project's build requirements.
You can specify the plugin version in
either the File > Project
Structure > Project menu in Android Studio, or
the top-level build.gradle.kts
file. The plugin version applies to
all modules built in that Android Studio project. The following example sets
the plugin to version 8.1.0 from the
build.gradle.kts
file:
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 }
Caution: You should not use dynamic dependencies in version
numbers, such as 'com.android.tools.build:gradle:2.+'
. Using
this feature can cause unexpected version updates and difficulty resolving
version differences.
If the specified plugin version has not been downloaded, Gradle downloads it the next time you build your project or click File > Sync Project with Gradle Files from the Android Studio menu bar.
Update Gradle
When you update Android Studio, you may receive a prompt to also update Gradle to the latest available version. You can choose to accept the update or manually specify a version based on your project's build requirements.
The following table lists which version of Gradle is required for each version of the Android Gradle plugin. For the best performance, you should use the latest possible version of both Gradle and the plugin.
Plugin version | Minimum required Gradle version |
---|---|
8.3 | 8.3 |
8.2 | 8.2 |
8.1 | 8.0 |
8.0 | 8.0 |
7.4 | 7.5 |
Older versions
Plugin version | Required Gradle version |
---|---|
7.3 | 7.4 |
7.2 | 7.3.3 |
7.1 | 7.2 |
7.0 | 7.0 |
4.2.0+ | 6.7.1 |
4.1.0+ | 6.5+ |
4.0.0+ | 6.1.1+ |
3.6.0 - 3.6.4 | 5.6.4+ |
3.5.0 - 3.5.4 | 5.4.1+ |
3.4.0 - 3.4.3 | 5.1.1+ |
3.3.0 - 3.3.3 | 4.10.1+ |
3.2.0 - 3.2.1 | 4.6+ |
3.1.0+ | 4.4+ |
3.0.0+ | 4.1+ |
2.3.0+ | 3.3+ |
2.1.3 - 2.2.3 | 2.14.1 - 3.5 |
2.0.0 - 2.1.2 | 2.10 - 2.13 |
1.5.0 | 2.2.1 - 2.13 |
1.2.0 - 1.3.1 | 2.2.1 - 2.9 |
1.0.0 - 1.1.3 | 2.2.1 - 2.3 |
You can specify the Gradle version in either the File >
Project Structure > Project menu in Android Studio,
or update your Gradle version using the command line.
The preferred way is to use the
Gradle Wrapper
command line tool, which updates the gradlew
scripts. The following
example sets the Gradle version to 8.1 using the Gradle Wrapper.
Note, you need to run this command twice to upgrade both Gradle and the
Gradle Wrapper itself (for more information, see
Upgrading the Gradle Wrapper).
gradle wrapper --gradle-version 8.1
However this might fail in some cases, for example if you've just updated AGP
and it's no longer compliant with the current Gradle version. In this case,
you need to edit the Gradle distribution reference in the
gradle/wrapper/gradle-wrapper.properties
file. The following
example sets the Gradle version to 8.1 in the
gradle-wrapper.properties
file.
...
distributionUrl = https\://services.gradle.org/distributions/gradle-8.1-bin.zip
...
Android Gradle plugin and Android Studio compatibility
The Android Studio build system is based on Gradle, and the Android Gradle plugin (AGP) adds several features that are specific to building Android apps. The following table lists which version of AGP is required for each version of Android Studio.
Android Studio version | Required AGP version |
---|---|
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 |
Older versions
Android Studio version | Required AGP version |
---|---|
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 |
For information on what’s new in the Android Gradle plugin, see the Android Gradle plugin release notes.
Versioning changes (November 2020)
We are updating the version numbering for Android Gradle plugin (AGP) to more closely match the underlying Gradle build tool.
Here are the notable changes:
AGP will now use semantic versioning, and breaking changes will be targeted for major releases.
There will be one major version of AGP released per year, aligned with the Gradle major release.
The release after AGP 4.2 will be version 7.0 and will require an upgrade to Gradle version 7.x. Every major release of AGP will require a major version upgrade in the underlying Gradle tool.
APIs will be deprecated approximately one year in advance, with replacement functionality made available concurrently. Deprecated APIs will be removed approximately one year later during the subsequent major update.
8.1.0 (July 2023)
Android Gradle plugin 8.1.0 is a major release that includes a variety of new features and improvements.
Compatibility
Minimum version | Default version | Notes | |
---|---|---|---|
Gradle | 8.0 | 8.0 | To learn more, see updating Gradle. |
SDK Build Tools | 33.0.1 | 33.0.1 | Install or configure SDK Build Tools. |
NDK | N/A | 25.1.8937393 | Install or configure a different version of the NDK. |
JDK | 17 | 17 | To learn more, see setting the JDK version. |
Kotlin DSL is the default for build configuration
New projects now use the Kotlin DSL (build.gradle.kts
) by default for build
configuration. This offers a better editing experience than the Groovy DSL
(build.gradle
) with syntax highlighting, code completion, and navigation to
declarations. Note that if you're using AGP 8.1 and the Kotlin DSL for build
configuration, you should use Gradle 8.1 for the best experience. To learn more,
see the Kotlin DSL migration guide.
Automatic per-app language support
Starting with Android Studio Giraffe Canary 7 and AGP 8.1.0-alpha07, you can
configure your app to support
per-app language preferences
automatically. Based on your project resources, the Android Gradle plugin
generates the LocaleConfig
file and adds a reference to it in the final manifest
file, so you no longer have to do it manually. AGP uses the resources in the
res
folders of your app modules and any library module dependencies to
determine the locales to include in the LocaleConfig
file.
Note that the automatic per-app language feature supports apps that run Android
13 (API level 33) or higher. To use the feature, you must set
compileSdkVersion
to 33 or higher. To configure per-app language preferences
for prior versions of Android, you still need to
use the APIs and in-app language pickers.
To enable automatic per-app language support, specify a default locale:
- In the app module's
res
folder, create a new file calledresources.properties
. In the
resources.properties
file, set the default locale with theunqualifiedResLocale
label. To form the locale names, combine the language code with the optional script and region codes, separating each with a dash:- Language: Use the two- or three-letter ISO 639-1 code.
- Script (optional): Use the ISO 15924code.
- Region (optional): Use either the two-letter ISO 3166-1-alpha-2 code or three-digit UN_M.49 code.
For example if your default locale is American English:
unqualifiedResLocale=en-US
AGP adds this default locale and any
alternative locales
you've specified, using values-*
directories in the res
folder, to the
auto-generated LocaleConfig
file.
Automatic per-app language support is off by default. To turn the feature on,
use the generateLocaleConfig
setting in the androidResources {}
block of the
module-level build.gradle.kts
file (build.gradle
file if you're using
Groovy):
Kotlin
android { androidResources { generateLocaleConfig = true } }
Groovy
android { androidResources { generateLocaleConfig true } }
Android Lint contains bytecode targeting JVM 17
Starting with AGP 8.1.0-alpha04, Android Lint contains bytecode targeting JVM
17. If you write custom lint checks, you need to compile with JDK 17 or higher
and specify jvmTarget = '17'
in your Kotlin compiler options.
To learn more about the lint tool, see Improve your code with lint checks.
Native library compression setting moved to DSL
Starting with AGP 8.1.0-alpha10, you'll get a warning if you don't configure native library compression using the DSL instead of the manifest. The following guidance explains how to update your configuration to use the DSL. To get help making these updates, use the AGP Upgrade Assistant (Tools > AGP Upgrade Assistant).
To use uncompressed native libraries, remove the android::extractNativeLibs
attribute from the manifest and add the following code to the module-level
build.gradle.kts
file (build.gradle
file if you're using Groovy):
Kotlin
android { packagingOptions { jniLibs { useLegacyPackaging = false } } }
Groovy
android { packagingOptions { jniLibs { useLegacyPackaging false } } }
Experimental build flags
These are experimental flags for configuring your build available in AGP 8.1.
Flag | Added in | Default value | Notes |
---|---|---|---|
android.experimental.useDefaultDebugSigningConfigForProfileableBuildtypes |
AGP 8.0 | false |
Enabling this with no signing configs specified causes AGP to use the default debug signing config when running a profileable or debuggable build. This flag is disabled by default to encourage build authors to declare specific profiling signing configs. |
android.experimental.library.desugarAndroidTest |
AGP 8.0 | false |
This flag lets library builders enable core library desugaring for test APKs without affecting the AAR produced, for example through linting. We plan to eventually support this behavior in the Variant API. |
android.experimental.testOptions.managedDevices.customDevice |
AGP 8.0 | false |
If enabled, Gradle Managed Devices allows a user-defined custom device type that can be provided by a plugin. This flag must be enabled if you want to use the Firebase Test Lab plugin. |
android.lint.printStackTrace |
AGP 8.0 | false |
If enabled, Android lint prints a stacktrace if it crashes. This flag
has the same functionality as the LINT_PRINT_STACKTRACE
environment variable. |
android.experimental.testOptions.managedDevices.maxConcurrentDevices |
AGP 8.0 | None | Specifies the maximum number of concurrent Gradle Managed Devices (AVDs) to be active at any one point in time. If the value is 0 or negative, there is no maximum number of devices. |
android.experimental.testOptions.installApkTimeout |
AGP 8.0 | None | The timeout duration in seconds to install an APK. If the value is 0 or negative, it will be set to a default value by UTP. |