Android Gradle plugin 8.3 release notes

The JCenter repository became read-only on March 31st, 2021. For more information, see JCenter service update.

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 Gradle plugin (AGP) 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.

To see what's been fixed in this version of the Android Gradle plugin, see the closed issues.

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:

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.3.0 from the build.gradle.kts file:

Kotlin

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

Groovy

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

Caution: You should not use dynamic dependencies in version numbers, such as 'com.android.tools.build:gradle:8.3.+'. 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 versionMinimum required Gradle version
8.4 (alpha)8.6-rc-1
8.38.4
8.28.2
8.18.0
8.08.0
7.47.5

Older versions

Plugin versionRequired Gradle version
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

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.3 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.3

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.3 in the gradle-wrapper.properties file.

...
distributionUrl = https\://services.gradle.org/distributions/gradle-8.3-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
Jellyfish | 2023.3.1 3.2-8.4
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.

Minimum versions of tools for Android API level

There are minimum versions of Android Studio and AGP that support a specific API level. Using lower versions of Android Studio or AGP than required by your project's targetSdk or compileSdk could lead to unexpected issues. We recommend using the latest preview version of Android Studio and AGP to work on projects that target preview versions of the Android OS. You can install preview versions of Android Studio alongside a stable version.

The minimum versions of Android Studio and AGP are as follows:

API level Minimum Android Studio version Minimum AGP version
VanillaIceCream preview Jellyfish | 2023.3.1 8.4
34 Hedgehog | 2023.1.1 8.1.1
33 Flamingo | 2022.2.1 7.2

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.

Compatibility

The maximum API level that Android Gradle plugin 8.3 supports is API level 34. Here is other compatibility info:

Minimum version Default version Notes
Gradle 8.4 8.4 To learn more, see updating Gradle.
SDK Build Tools 34.0.0 34.0.0 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.

The following are new features in Android Gradle plugin 8.3.

Support for Gradle Version Catalogs

Android Studio supports TOML-based Gradle Version Catalogs, a feature that lets you manage dependencies in one central location and share dependencies across modules or projects. Android Studio now makes it easier to configure version catalogs through editor suggestions and integration with the Project Structure dialog. Learn how to set up and configure Gradle Version Catalogs or how to migrate your build to version catalogs.

Code completion and navigation

Android Studio offers code completion when you're editing a version catalog in the TOML file format or adding a dependency from a version catalog to a build file. To use code completion, press Ctrl+Space (Command+Space on macOS). In addition, you can quickly navigate from a dependency reference in your app's build.gradle file to where it's declared in the version catalog by pressing Ctrl+b (Command+b on macOS).

Code completion when adding a dependency

Integration with the Project Structure dialog

If your project uses a version catalog defined in the TOML file format, you can edit variables you've defined there through the Project Structure dialog Variables view (File > Project Structure > Variables) in Android Studio. For each version catalog, there is a drop-down that lists the variables from that catalog. To edit a variable, click its value and overwrite it. When you save these changes, the TOML file is updated accordingly.

Variables from a version catalog in the Project Structure dialog

You can also update dependencies in the Project Structure dialog Dependencies view (File > Project Structure > Dependencies). To update versions using the Project Structure dialog, navigate to the module and dependency you want to edit, and then update the Requested Version field. When you save these changes, the TOML file is updated accordingly. Note that if the dependency version was defined using a variable, updating the version directly this way replaces the variable with a hardcoded value. Also be aware that removing a dependency from a build file, whether you use the Project Structure dialog or not, doesn't remove the dependency from the version catalog.

Dependencies from a version catalog in the Project Structure dialog

Known issues and limitations

The following are known issues or limitations with Gradle Version Catalogs support in Android Studio.

  • Error highlighting plugin alias declarations in Kotlin script files: when you add a plugin declaration of the form alias(libs.plugins.example), the editor adds a red underline under the libs part. This is a known issue in Gradle versions 8.0 and lower and will be resolved in a future release of Gradle.

  • Android Studio support only for version catalogs in TOML format: currently the Android Studio code completion, navigation, and Project Structure dialog support is only available for version catalogs defined in the TOML file format. However, you can still add a version catalog directly in the settings.gradle file and use its dependencies in your project.

  • Navigation for KTS build files not supported: navigating to a dependency definition in a version catalog by using Control+click (Command+click on macOS) isn't yet supported for build files written using Kotlin script.

  • Firebase Assistant adds dependencies directly in build scripts: the Firebase Assistant adds dependencies directly to your build scripts instead of through version catalogs.

  • "Find usages" functionality not supported: finding usages of a version catalog variable in other build files isn't yet supported, whether the build file is in KTS or Groovy. That is, using Control+click (Command+click on macOS) on a variable definition in a version catalog doesn't lead to the build files where the variable is used.

  • The Project Structure dialog in Android Studio shows multiple catalog files if they're in the root gradle folder, but doesn't show catalogs for a composite build. For example, if you have two catalog files—one for your app and one for a composite build—the Project Structure dialog only shows the app catalog file. You can use a composite build, but you have to edit its TOML file directly.

Additional SDK insights: policy issues

Android Studio displays lint warnings in build.gradle.kts and build.gradle files and in the Project Structure Dialog for public SDKs that have Play policy violations in the Google Play SDK Index. You should update any dependencies that violate Play policies because these violations could prevent you from publishing to the Google Play Console in the future. The policy violation warnings supplement the outdated version warnings displayed by Android Studio.

Android Studio compileSdk version support

Android Studio displays a warning if your project uses a compileSdk that isn't supported by the current version of Android Studio. If available, it also suggests moving to a version of Android Studio that supports the compileSdk used by your project. Keep in mind that upgrading Android Studio might also require you upgrade AGP. AGP also displays a warning in the Build tool window if the compileSdk used by your project isn't supported by the current version of AGP.

Lint behavior changes

Starting with Android Gradle plugin 8.3.0-alpha02, when running lint on a module, separate lint analysis tasks are run for the main and test components of the module. The reason for this change is to improve performance. To revert to the earlier behavior, set android.experimental.lint.analysisPerComponent=false in your gradle.properties file.