Plug-in Android Gradle 9.0.1 (janvier 2026)

Le plug-in Android Gradle 9.0 est une version majeure qui apporte des modifications d'API et de comportement.

Pour passer à la version 9.0.1 du plug-in Android Gradle, utilisez l'assistant de mise à niveau du plug-in Android Gradle. L'assistant de mise à niveau AGP permet de préserver les comportements existants lors de la mise à niveau de votre projet, le cas échéant. Vous pouvez ainsi mettre à niveau votre projet pour utiliser AGP 9.0, même si vous n'êtes pas prêt à adopter toutes les nouvelles valeurs par défaut d'AGP 9.0.

Deux compétences d'agent sont également disponibles pour faciliter le processus de migration. Pour une application non KMP, essayez la compétence de mise à niveau AGP 9 du dépôt de compétences Android. Pour une application KMP, essayez la compétence de mise à niveau AGP 9 de JetBrains. Pour en savoir plus sur l'utilisation des compétences dans Android Studio, consultez Étendre le mode Agent avec des compétences.

Compatibilité

Le niveau d'API maximal compatible avec le plug-in Android Gradle 9.0 est le niveau d'API 36.1. Voici d'autres informations sur la compatibilité :

Les classes DSL android n'implémentent désormais que les nouvelles interfaces publiques.

Ces dernières années, nous avons introduit de nouvelles interfaces pour notre DSL et notre API afin de mieux contrôler les API publiques. Les versions 7.x et 8.x d'AGP utilisaient toujours les anciens types de DSL (par exemple, BaseExtension), qui implémentaient également les nouvelles interfaces publiques, afin de maintenir la compatibilité à mesure que les interfaces évoluaient.

AGP 9.0 utilise exclusivement nos nouvelles interfaces DSL, et les implémentations ont été remplacées par de nouveaux types entièrement masqués. Cela supprime également l'accès à l'ancienne API de variante obsolète.

Pour passer à AGP 9.0, vous devrez peut-être effectuer les opérations suivantes :

• Assurez-vous que votre projet est compatible avec Kotlin intégré : le plug-in org.jetbrains.kotlin.android n'est pas compatible avec le nouveau DSL.

• Passer les projets KMP au plug-in de bibliothèque Android Gradle pour KMP : l'utilisation du plug-in org.jetbrains.kotlin.multiplatform dans le même sous-projet Gradle que les plug-ins com.android.library et com.android.application n'est pas compatible avec le nouveau DSL.

• Mettez à jour vos fichiers de compilation : Bien que le changement d'interfaces vise à conserver un DSL aussi similaire que possible, il peut y avoir quelques petites modifications.

• Mettez à jour votre logique de compilation personnalisée pour référencer le nouveau DSL et la nouvelle API : remplacez toutes les références au DSL interne par les interfaces DSL publiques. Dans la plupart des cas, il s'agira d'un remplacement un à un. Remplacez toute utilisation de applicationVariants et d'API similaires par la nouvelle API androidComponents. Cela peut être plus complexe, car l'API androidComponents est conçue pour être plus stable afin de maintenir la compatibilité des plug-ins plus longtemps. Pour obtenir des exemples, consultez nos recettes Gradle.

• Mettre à jour les plug-ins tiers : certains plug-ins tiers peuvent toujours dépendre d'interfaces ou d'API qui ne sont plus exposées. Migrez vers des versions de ces plug-ins compatibles avec AGP 9.0.

Le passage aux nouvelles interfaces DSL empêche les plug-ins et les scripts de compilation Gradle d'utiliser diverses API obsolètes, y compris :

androidComponents {
    onVariants() { variant ->
        variant.signingConfig
            .enableV1Signing.set(false)
    }
}

androidComponents {
    beforeVariants(
        selector()
            .withBuildType("debug")
            .withFlavor("color", "blue")
    ) { variantBuilder ->
        variantBuilder.enable = false
    }
  }

Si vous passez à AGP 9.0 et que le message d'erreur suivant s'affiche, cela signifie que votre projet fait toujours référence à certains des anciens types :

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

Si vous êtes bloqué par des plug-ins tiers incompatibles, vous pouvez désactiver l'option et récupérer les anciennes implémentations du DSL, ainsi que l'ancienne API de variante. Pendant ce temps, les nouvelles interfaces sont également disponibles, et vous pouvez toujours mettre à jour votre propre logique de compilation vers la nouvelle API. Pour désactiver cette option, incluez cette ligne dans votre fichier gradle.properties :

android.newDsl=false

Pour une migration plus progressive, AGP 9.4 vous permet de désactiver des modules individuels. Pour savoir comment procéder, consultez Désactivation du module de l'API Variant.

Les classes précédentes sont marquées comme obsolètes dans l'AGP 9.0. Cela signifie que les projets qui désactivent l'option newDsl verront des avertissements d'abandon, y compris sur le bloc android lui-même.

Vous pouvez également commencer à passer aux nouvelles API avant de passer à AGP 9.0. Les nouvelles interfaces sont présentes dans de nombreuses versions d'AGP. Vous pouvez donc avoir un mélange d'anciennes et de nouvelles interfaces. La documentation de référence de l'API AGP présente la surface de l'API pour chaque version d'AGP, ainsi que la date d'ajout de chaque classe, méthode et champ.

Nous contactons les auteurs des plug-ins couramment utilisés pour les aider à adapter et à publier des plug-ins entièrement compatibles avec les nouveaux modes. Nous continuerons également à améliorer l'assistant de mise à niveau AGP dans Android Studio pour vous guider tout au long de la migration.

Si vous constatez que le nouveau DSL ou la nouvelle API Variant ne disposent pas de certaines fonctionnalités, veuillez signaler un problème dès que possible.

Kotlin intégré

Le plug-in Android Gradle 9.0 introduit la compatibilité intégrée avec Kotlin et l'active par défaut. Cela signifie que vous n'avez plus besoin d'appliquer le plug-in org.jetbrains.kotlin.android (ou kotlin-android) dans vos fichiers de compilation pour compiler les fichiers sources Kotlin. Cela simplifie l'intégration de Kotlin à AGP, évite l'utilisation d'API obsolètes et améliore les performances dans certains cas.

Par conséquent, lorsque vous mettez à niveau votre projet vers AGP 9.0, vous devez également migrer vers Kotlin intégré ou désactiver cette option.

Vous pouvez également désactiver de manière sélective la compatibilité intégrée avec Kotlin pour les sous-projets Gradle qui n'ont pas de sources Kotlin.

Dépendance d'exécution au plug-in Gradle Kotlin

Pour fournir une compatibilité Kotlin intégrée, le plug-in Android Gradle 9.0 dépend désormais de l'environnement d'exécution du plug-in Kotlin Gradle (KGP) 2.2.10. Cela signifie que vous n'avez plus besoin de déclarer une version de KGP. Si vous utilisez une version de KGP antérieure à la version 2.2.10, Gradle mettra automatiquement à niveau votre version de KGP vers la version 2.2.10. De même, si vous utilisez une version de KSP antérieure à la version 2.2.10-2.0.2, AGP la mettra à niveau vers la version 2.2.10-2.0.2 pour qu'elle corresponde à la version de KGP.

Passer à une version supérieure du KGP

Pour utiliser une version plus récente de KGP ou KSP, ajoutez ce qui suit à votre fichier de compilation de premier niveau :

buildscript {
    dependencies {
        // For KGP
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:KGP_VERSION")

        // For KSP
        classpath("com.google.devtools.ksp:symbol-processing-gradle-plugin:KSP_VERSION")
    }
}

Passer à une version antérieure du KGP

Vous ne pouvez passer à une version antérieure du KGP que si vous avez désactivé Kotlin intégré. En effet, AGP 9.0 active Kotlin intégré par défaut, et Kotlin intégré nécessite KGP 2.2.10 ou version ultérieure.

Pour utiliser une version antérieure de KGP ou de KSP, déclarez cette version dans votre fichier de compilation de premier niveau à l'aide d'une déclaration de version stricte :

buildscript {
    dependencies {
        // For KGP
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("KGP_VERSION") }
        }

        // For KSP
        classpath("com.google.devtools.ksp:symbol-processing-gradle-plugin") {
            version { strictly("KSP_VERSION") }
        }
    }
}

Notez que la version minimale du KGP vers laquelle vous pouvez revenir est la version 2.0.0.

Compatibilité de l'IDE avec les outils de test

AGP 9.0 est entièrement compatible avec l'IDE Android Studio pour les outils de test.

Plug-in de bibliothèque fusionnée

Le plug-in Fused Library (preview) vous permet de publier plusieurs bibliothèques sous la forme d'un seul fichier AAR de bibliothèque Android. Cela peut permettre à vos utilisateurs de dépendre plus facilement de vos artefacts publiés.

Pour en savoir plus sur les premiers pas, consultez Publier plusieurs bibliothèques Android en une seule avec Fused Library.

Changements de comportement

Le plug-in Android Gradle 9.0 présente les nouveaux comportements suivants :

AGP 9.0 inclut des mises à jour des valeurs par défaut des propriétés Gradle suivantes. Vous pouvez ainsi choisir de conserver le comportement d'AGP 8.13 lors de la mise à niveau :

android {
  defaultConfig {
    testInstrumentationRunner = "..."
  }
}

android {
  buildFeatures {
    resValues = true
  }
}

android {
  buildFeatures {
    shaders = true
  }
}

Fonctionnalités supprimées

Le plug-in Android Gradle 9.0 supprime les fonctionnalités suivantes :

• Compatibilité avec les applications Wear OS intégrées
  AGP 9.0 supprime la compatibilité avec l'intégration d'applications Wear OS, qui n'est plus compatible avec Play. Cela inclut la suppression des configurations wearApp et du DSL AndroidSourceSet.wearAppConfigurationName. Pour savoir comment publier votre application sur Wear OS, consultez Distribuer votre application sur Wear OS.
• Tâche de rapport androidDependencies et sourceSets
• Prise en charge des APK divisés par densité
  AGP 9.0 ne permet plus de créer des APK divisés en fonction de la densité de l'écran. La fonctionnalité et les API associées ont été supprimées. Pour diviser les APK en fonction de la densité de l'écran à l'aide d'AGP 9.0 ou version ultérieure, utilisez des app bundles.

DSL modifié

Le plug-in Android Gradle 9.0 comporte les modifications destructives suivantes du DSL :

• La paramétrisation de CommonExtension a été supprimée.

  En soi, il s'agit d'une modification destructive au niveau de la source pour éviter d'autres modifications destructives au niveau de la source à l'avenir. Cela signifie également que les méthodes de bloc doivent passer de CommonExtension à ApplicationExtension, LibraryExtension, DynamicFeatureExtension et TestExtension.

  Lorsque vous mettez à niveau votre projet vers AGP 9.0, refactorisez le code du plug-in Gradle qui utilise ces paramètres ou les méthodes de bloc. Par exemple, le plug-in suivant est mis à jour pour supprimer le paramètre de type et ne pas s'appuyer sur les méthodes de bloc supprimées :

  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)
          }
      }
  }
  

  Pour les plug-ins qui ciblent une plage de versions d'AGP, l'utilisation directe du getter est compatible au niveau binaire avec les versions d'AGP antérieures à la version 9.0.

DSL supprimé

Le plug-in Android Gradle 9.0 supprime les éléments suivants :

• AndroidSourceSet.jni, car elle ne fonctionnait pas.

• AndroidSourceSet.wearAppConfigurationName, car elle est liée à la suppression de la compatibilité avec les applications Wear OS intégrées.

• BuildType.isRenderscriptDebuggable, car elle ne fonctionnait pas.

• DependencyVariantSelection. Il est remplacé par DependencySelection, qui est exposé en tant que kotlin.android.localDependencySelection.

• Installation.installOptions(String). Elle est remplacée par la propriété modifiable de Installation.installOptions.

• Le bloc PostProcessing expérimental, mais jamais stabilisé.

• ProductFlavor.setDimension, qui est remplacé par la propriété dimension

• LanguageSplitOptions, qui n'était utile que pour Google Play Instant, qui est obsolète.

• DensitySplit, car la fonctionnalité n'est plus disponible. La solution de remplacement consiste à utiliser des app bundles.

API supprimées

Le plug-in Android Gradle 9.0 supprime les éléments suivants :

• AndroidComponentsExtension.finalizeDSl. Il est remplacé par finalizeDsl.

• Component.transformClassesWith. Il est remplacé par Instrumentation.transformClassesWith.

• Component.setAsmFramesComputationMode. Il est remplacé par Instrumentation.setAsmFramesComputationMode.

• ComponentBuilder.enabled. Il est remplacé par ComponentBuilder.enable.

• DependenciesInfoBuilder.includedInApk. Il est remplacé par includeInApk.

• DependenciesInfoBuilder.includedInBundle. Il est remplacé par includeInBundle.

• GeneratesApk.targetSdkVersion : remplacé par targetSdk.

• Variant.minSdkVersion. Il est remplacé par minSdk.

• Variant.maxSdkVersion : remplacé par maxSdk.

• Variant.targetSdkVersion. Il est remplacé par targetSdk.

• Variant.unitTest, car elle n'était pas applicable au plug-in com.android.test. unitTest est disponible sur les sous-types VariantBuilder étendant HasUnitTest.

• VariantBuilder.targetSdk et targetSdkPreview, car ils n'étaient pas pertinents dans les bibliothèques. Utilisez plutôt GeneratesApkBuilder.targetSdk ou GeneratesApkBuilder.targetSdkPreview.

• VariantBuilder.enableUnitTest, car elle n'était pas applicable au plug-in com.android.test. enableUnitTest est disponible sur les sous-types VariantBuilder qui étendent HasUnitTestBuilder.

• VariantBuilder.unitTestEnabled est supprimé au profit de enableUnitTest, dont le nom est plus cohérent, sur les sous-types VariantBuilder qui étendent HasUnitTestBuilder.

• VariantOutput.enable. Il est remplacé par enabled.

• Les éléments FeaturePlugin et FeatureExtension obsolètes et désactivés.

• Les API BaseExtension.registerTransform obsolètes et désactivées, qui n'étaient conservées que pour permettre la compilation avec la dernière version d'AGP tout en ciblant l'exécution sur AGP 4.2 ou version antérieure.

Propriétés Gradle supprimées

Les propriétés Gradle suivantes ont été initialement ajoutées pour désactiver globalement les fonctionnalités activées par défaut.

Ces fonctionnalités sont désactivées par défaut depuis AGP 8.0 ou version antérieure. Activez ces fonctionnalités uniquement dans les sous-projets qui les utilisent pour une compilation plus efficace.

android {
  buildFeatures {
    aidl = true
  }
}

android {
  buildFeatures {
    renderScript = true
  }
}

Propriétés Gradle appliquées

AGP 9.0 génère une erreur si vous définissez les propriétés Gradle suivantes.

L'assistant de mise à niveau du plug-in Android Gradle ne mettra pas à niveau vers AGP 9.0 les projets qui utilisent ces propriétés.

Modifications de R8

Les modifications suivantes de R8 sont incluses dans AGP 9.0.0.

Nouvelle option de configuration -processkotlinnullchecks

Nous avons ajouté la nouvelle option R8 -processkotlinnullchecks pour configurer R8 afin de traiter les vérifications de valeurs nulles Kotlin. L'option accepte un argument obligatoire qui doit correspondre à l'une des trois valeurs suivantes : keep, remove_message et remove. L'option traite les vérifications de valeurs nulles suivantes ajoutées par le compilateur Kotlin :

class kotlin.jvm.internal.Intrinsics {
  void checkNotNull(java.lang.Object);
  void checkNotNull(java.lang.Object, java.lang.String);
  void checkExpressionValueIsNotNull(
      java.lang.Object, java.lang.String);
  void checkNotNullExpressionValue(
      java.lang.Object, java.lang.String);
  void checkReturnedValueIsNotNull(
      java.lang.Object, java.lang.String);
  void checkReturnedValueIsNotNull(
      java.lang.Object, java.lang.String, java.lang.String);
  void checkFieldIsNotNull(java.lang.Object, java.lang.String);
  void checkFieldIsNotNull(
      java.lang.Object, java.lang.String, java.lang.String);
  void checkParameterIsNotNull(java.lang.Object, java.lang.String);
  void checkNotNullParameter(java.lang.Object, java.lang.String);
}

Les valeurs d'option, classées de la plus faible à la plus forte, ont l'effet suivant :

• keep ne modifie pas les vérifications.
• remove_message réécrit chaque appel de méthode de vérification en un appel à getClass() sur le premier argument de l'appel (en conservant la vérification de la valeur nulle, mais sans message).
• remove supprime complètement les vérifications.

Par défaut, R8 utilise remove_message. Toute spécification de -processkotlinnullchecks remplacera cette valeur. Si elle est spécifiée plusieurs fois, la valeur la plus forte est utilisée.

Arrêter de propager les informations de conservation aux méthodes associées

Lorsque les règles de conservation correspondaient à des méthodes d'interface soumises à la désucration, R8 transférait auparavant en interne les bits interdire l'optimisation et interdire la minification aux méthodes complémentaires synthétisées.

À partir d'AGP 9.0, les règles de conservation ne s'appliquent plus aux méthodes associées. Cela est cohérent avec le fait que les règles de conservation ne s'appliquent pas aux autres champs/méthodes/classes synthétisés par le compilateur.

En transférant les bits disallow optimization et disallow shrinking vers les méthodes associées, le cas d'utilisation suivant était auparavant accepté :

1. Compilez une bibliothèque avec des méthodes d'interface default/static/private vers DEX avec minSdk < 24 et des règles qui conservent les méthodes d'interface.
2. Compilez une application avec la bibliothèque sur le chemin de classe et -applymapping.
3. Fusionnez l'application et la bibliothèque.

Notez que cela ne fonctionne qu'avec -applymapping, car le bit disallow obfuscation n'est pas transféré aux méthodes associées. Autrement dit, les classes associées générées à l'étape 1 auraient des noms de méthode obscurcis.

À l'avenir, ce cas d'utilisation ne sera plus pris en charge pour minSdk < 24. Pour contourner ce problème, procédez comme suit :

1. Désucrez la bibliothèque avec les méthodes d'interface default/static/private pour classer les fichiers avec minSdk < 24.
2. Compilez l'artefact désucré à l'aide de R8 et des règles qui conservent les méthodes d'interface sur les classes associées.
3. Compilez l'application avec la bibliothèque sur le chemin de classe.
4. Fusionnez l'application et l'artefact désucré.

Autre effet secondaire : il n'est plus possible de conserver les attributs de classe interne et de méthode englobante pour les classes anonymes et locales dans les méthodes d'interface associées.

Remplacez le fichier source d'émission par défaut par r8-map-id-<MAP_ID>.

Cette modification est disponible dans AGP à partir de la version 8.12.0.

L'attribut de fichier source émis par défaut pour une classe passe de SourceFile à r8-map-id-<MAP_ID> lorsqu'un retraçage est requis (c'est-à-dire lorsque l'obscurcissement ou l'optimisation est activé).

À partir d'une trace de la pile obscurcie, le nouvel attribut de fichier source permet d'extraire l'ID du fichier de mappage requis pour le retraçage, qui peut être utilisé pour permettre le retraçage automatisé des traces de la pile dans Logcat.

Si un attribut de fichier source personnalisé est utilisé (-renamesourcefileattribute), il continue d'avoir la priorité.

En mode de compatibilité ProGuard (lorsque gradle.properties contient android.enableR8.fullMode=false), l'émission d'un attribut de fichier source de r8-map-id-<MAP_ID> ne prend effet que si l'attribut SourceFile n'est pas conservé. Les applications qui utilisent le mode de compatibilité ProGuard et souhaitent inclure l'ID du fichier de mappage dans leurs traces de la pile doivent supprimer -keepattributes SourceFile (ou migrer vers le mode complet R8).

L'ID de carte utilisé dans r8-map-id-<MAP_ID> est le hachage complet de la carte, et non un préfixe de sept caractères du hachage de la carte, qui était utilisé auparavant.

Activer l'utilisation de noms synthétiques minimisés dans le désucrage L8

Le nom des classes synthétiques générées par D8 contient normalement la sous-chaîne $$ExternalSynthetic, qui vous indique qu'il s'agit d'un élément synthétique généré par D8. De plus, le nom de l'élément synthétique encode également le type synthétique (par exemple, Backport, Lambda). Cela a un impact négatif sur la taille du fichier DEX obtenu, car les noms de classe occupent plus d'espace dans le pool de chaînes.

AGP 9.0 configure L8 (désucrage de la bibliothèque principale) de sorte que le fichier DEX contenant toutes les classes j$ utilise un nouveau format de nom de classe raccourci pour les classes synthétiques. Le nouveau nom de la classe utilise un ID numérique (par exemple, $1).

Supprimer la compatibilité avec -addconfigurationdebugging

AGP 9.0 ne prend plus en charge -addconfigurationdebugging. Le compilateur affiche désormais un avertissement si l'option est utilisée.

Suppression de la prise en charge de la génération de règles L8 à partir de D8/R8

Cette modification ne concerne que les développeurs qui utilisent directement la ligne de commande ou les API D8/R8.

R8 9.0 ne permet plus de générer des règles de conservation pour L8 à partir de D8 et R8. Utilisez plutôt TraceReferences à cette fin.

Plus précisément, les méthodes D8Command.builder.setDesugaredLibraryKeepRuleConsumer et R8Command.Builder.setDesugaredLibraryKeepRuleConsumer sont supprimées, et la compatibilité avec --desugared-lib-pg-conf-output est supprimée des options de ligne de commande de D8 et R8.

Problèmes résolus

Plug-in Android Gradle 9.0.0