Release notes for Android Gradle plugin preview

This page contains release notes for preview releases of the Android Gradle plugin (AGP).

Android Gradle plugin 9.0

Android Gradle plugin 9.0 is a new major release of AGP, and brings API and behavior changes.

To update to Android Gradle plugin 9.0.0-alpha05, use the Android Gradle plugin Upgrade Assistant in Android Studio Narwhal 4 Feature Drop | 2025.1.4.

The AGP upgrade assistant helps preserve existing behaviors when upgrading your project when appropriate, allowing you to upgrade your project to use AGP 9.0, even if you're not ready to adopt all the new defaults in AGP 9.0.

Compatibility

The maximum Android API level that Android Gradle plugin 9.0.0-alpha05 supports is API level 36.

Android Gradle plugin 9.0.0-alpha05 requires Gradle 9.0.0.

The android DSL classes now only implement the new public interfaces

Over the last several years, we have introduced new interfaces for our DSL and API in order to better control which APIs are public. AGP versions 7.x and 8.x still used the old DSL types (for example BaseExtension) which also implemented the new public interfaces, in order to maintain compatibility as work progressed on the interfaces.

AGP 9.0 uses our new DSL interfaces exclusively, and the implementations have changed to new types that are fully hidden. This changes also removes access to the old, deprecated, variant API.

To update to AGP 9.0, you might need to do the following:

• Switch to built-in Kotlin: The org.jetbrains.kotlin.android plugin is not compatible with the new DSL.

• Switch KMP projects to the Android Gradle Library Plugin for KMP: Using the org.jetbrains.kotlin.multiplatform plugin in the same Gradle subproject as the com.android.library and com.android.application plugins is not compatible with the new DSL.

• Update your build files: While the change of interfaces is meant to keep the DSL as similar as possible, there might be some small changes.

• Update your custom build logic to reference the new DSL and API: Replace any references to the internal DSL with the public DSL interfaces. In most cases this will be a one-to-one replacement. Replace any use of the applicationVariants and similar APIs with the new androidComponents API. This might be more complex, as the androidComponents API is designed to be more stable to keep plugins compatible longer. Check our Gradle Recipes for examples.

• Update third-party plugins: Some third-party plugins might still depend on interfaces or APIs that are no longer exposed. Migrate to versions of those plugins which are compatible with AGP 9.0.

If you update to AGP 9.0 and see the following error message, it means that your project is still referencing some of the old types:

java.lang.ClassCastException: class com.android.build.gradle.internal.dsl.ApplicationExtensionImpl$AgpDecorated_Decorated
cannot be cast to class com.android.build.gradle.BaseExtension

If you are blocked by incompatible third-party plugins, you can opt out and get back the old implementations for the DSL, as well as the old variant API. While doing this, the new interfaces are also available, and you can still update your own build logic to the new API. To opt out, include this line in your gradle.properties file:

android.newDsl=false

You can also start upgrading to the new APIs before upgrading to AGP 9.0. The new interfaces have been present for many AGP versions and so you can have a mix of new and old. The AGP API reference docs show the API surface for each AGP version, and when each class, method and field was added.

During the 9.0 alpha phase we're reaching out to plugin authors to help them adapt and release plugins that are fully compatible with the new modes, and will enhance the AGP Upgrade Assistant in Android Studio to guide you through the migration.

If you find that the new DSL or Variant API are missing capabilities or features, please file an issue as soon as possible.

Built-in Kotlin

Android Gradle plugin 9.0 includes built-in support compiling Kotlin, replacing the separately applied Kotlin plugin. This simplifies the integration with AGP, avoiding the use of the deprecated APIs and improving performance in some cases.

Android Gradle plugin 9.0 has a runtime dependency on Kotlin Gradle plugin 2.2.10, which is the minimum version required for built-in kotlin support.

You can opt out of built-in Kotlin by setting android.builtInKotlin=false.

If you have opted out of built-in Kotlin and also need to use an older version of the Kotlin Gradle plugin, you can force the downgrade:

buildscript {
    dependencies {
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("2.0.0") } // or another version that you want to use
        }
    }
}

Behavior changes

Android Gradle plugin 9.0 has the following new behaviors:

AGP 9.0 includes updates to the following Gradle properties' defaults. This gives you the choice to preserve the AGP 8.13 behavior when upgrading:

android {
  buildFeatures {
    resValues = true
  }
}

android {
  buildFeatures {
    shaders = true
  }
}

Removed features

Android Gradle plugin 9.0 removes the following functionality:

• Embedded Wear OS app support
  AGP 9.0 removes support for embedding Wear OS apps, which is no longer supported in Play. This includes removing the wearApp configurations and the AndroidSourceSet.wearAppConfigurationName DSL. See Distribute to Wear OS for how to publish your app to Wear OS.
• androidDependencies and sourceSets report task

Changed DSL

Android Gradle plugin 9.0 has the following breaking DSL changes:

• The parameterization of CommonExtension has been removed.

  In itself, this is only a source-level breaking change to help avoid future source-level breaking changes, but it also means that the block methods need to move from CommonExtension to ApplicationExtension, LibraryExension, DynamicFeatureExtension and TestExtension.

  When upgrading your project to AGP 9.0, refactor Gradle plugin code which uses those parameters or the block methods. For example the following plugin is updated to remove the type parameter and not rely on the removed block methods:

  AGP 8.13

  val commonExtension: CommonExtension<*, *, *, *, *, *> =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig {
          minSdk {
              version = release(28)
          }
      }
  }
  

  AGP 9.0

  val commonExtension: CommonExtension =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig.apply {
          minSdk {
              version = release(28)
          }
      }
  }
  

  For plugins which target a range of AGP versions, using the getter directly is binary compatible with AGP versions lower than 9.0.

Removed DSL

Android Gradle plugin 9.0 removes:

• AndroidComponentsExtension.finalizeDSl. It is replaced by finalizeDsl

• AndroidSourceSet.jni, because it was not functional.

• AndroidSourceSet.wearAppConfigurationName, as it relates to the removed embedded Wear OS app support.

• BuildType.isRenderscriptDebuggable, because it was not functional.

• Component.transformClassesWith. It is replaced by Instrumentation.transformClassesWith

• Component.setAsmFramesComputationMode. It is replaced by Instrumentation.setAsmFramesComputationMode

• DependenciesInfoBuilder.includedInApk. Is is replaced by includeInApk

• DependenciesInfoBuilder.includedInBundle. Is is replaced by includeInBundle

• ComponentBuilder.enabled. It is replaced by ComponentBuilder.enable.

• DependencyVariantSelection. It is replaced By DependencySelection, which is exposed as kotlin.android

• GeneratesApk.targetSdkVersion. Is is replaced by targetSdk

• Installation.installOptions(String). It is replaced by the mutable property of Installation.installOptions.

• Variant.minSdkVersion. Is is replaced by minSdk

• Variant.maxSdkVersion. Is is replaced by maxSdk

• Variant.targetSdkVersion. Is is replaced by targetSdk

• VariantBuilder.targetSdk and targetSdkPreview, as they were not meaningful in libraries. Use GeneratesApkBuilder.targetSdk or GeneratesApkBuilder.targetSdkPreview instead.

• VariantOutput.enable. Is is replaced by enabled

• The experimental, but never stabilized PostProcessing block.

• ProductFlavor.setDimension, which is replaced by the dimension property

• LanguageSplitOptions, which was only useful for Google Play Instant, which is deprecated.

• Variant.unitTest, as it was not applicable to the com.android.test plugin. unitTest is available on VariantBuilder subtypes extending HasUnitTest.

• VariantBuilder.enableUnitTest, as it was not applicable to the com.android.test plugin. enableUnitTest is available on VariantBuilder subtypes extending HasUnitTestBuilder.

• VariantBuilder.unitTestEnabled is removed in favor of the more consistently named enableUnitTest on the VariantBuilder subtypes extending HasUnitTestBuilder.

Removed Gradle properties

The following Gradle properties were initially added as ways to globally disable features that were enabled by default.

These features have been disabled by default since AGP 8.0 or lower. Enable these features in only the sub-projects that use them for a more efficient build.

android {
  buildFeatures {
    aidl = true
  }
}

android {
  buildFeatures {
    renderScript = true
  }
}

Removed APIs

Android Gradle plugin 9.0 removes:

• The deprecated and disabled BaseExtension.registerTransform APIs, which only remained to allow compiling against the latest AGP version while targeting running on AGP 4.2 or lower.

• The deprecated and disabled FeaturePlugin and FeatureExtension.

Enforced Gradle properties

AGP 9.0 throws an error if you set the following Gradle properties.

The Android Gradle plugin Upgrade Assistant won't upgrade projects to AGP 9.0 that use these properties.