Complemento de Android para Gradle 9.0.1 (enero de 2026)

El complemento de Android para Gradle 9.0 es una versión importante que incluye cambios en la API y el comportamiento.

Para actualizar al complemento de Android para Gradle 9.0.1, usa el Asistente de actualización del complemento de Android para Gradle. El asistente de actualización del AGP ayuda a conservar los comportamientos existentes cuando actualizas tu proyecto, si es apropiado, lo que te permite actualizar tu proyecto para usar AGP 9.0, incluso si no estás listo para implementar todos los nuevos valores predeterminados en AGP 9.0.

También hay dos habilidades de agente disponibles para facilitar el proceso de actualización. Para una app que no sea de KMP, prueba la habilidad de actualización de AGP 9 del repositorio de habilidades de Android. Para una app de KMP, prueba la habilidad de actualización de AGP 9 de JetBrains. Para obtener más información sobre el uso de habilidades en Android Studio, consulta Cómo extender el modo de agente con habilidades.

Compatibilidad

El nivel de API máximo que admite el complemento de Android para Gradle 9.0 es el nivel de API 36.1. A continuación, se incluye otra información sobre la compatibilidad:

Las clases de DSL de android ahora solo implementan las nuevas interfaces públicas.

En los últimos años, presentamos interfaces nuevas para nuestra DSL y API con el objetivo de controlar mejor qué APIs son públicas. Las versiones 7.x y 8.x del AGP aún usaban los tipos de DSL antiguos (por ejemplo, BaseExtension), que también implementaban las nuevas interfaces públicas, para mantener la compatibilidad a medida que se avanzaba en las interfaces.

AGP 9.0 usa nuestras nuevas interfaces de DSL de forma exclusiva, y las implementaciones cambiaron a tipos nuevos que están completamente ocultos. Esto también quita el acceso a la API de variantes anterior, que ya no está disponible.

Para actualizar a AGP 9.0, es posible que debas hacer lo siguiente:

• Asegúrate de que tu proyecto sea compatible con Kotlin integrado: El complemento org.jetbrains.kotlin.android no es compatible con el nuevo DSL.

• Cambia los proyectos de KMP al complemento de biblioteca de Android para Gradle para KMP: El uso del complemento org.jetbrains.kotlin.multiplatform en el mismo subproyecto de Gradle que los complementos com.android.library y com.android.application no es compatible con el nuevo DSL.

• Actualiza tus archivos de compilación: Si bien el cambio de interfaces tiene como objetivo mantener la DSL lo más similar posible, puede haber algunos cambios pequeños.

• Actualiza la lógica de compilación personalizada para hacer referencia a la nueva DSL y API: Reemplaza cualquier referencia a la DSL interna por las interfaces de la DSL pública. En la mayoría de los casos, será un reemplazo uno a uno. Reemplaza cualquier uso de la API de applicationVariants y APIs similares por la nueva API de androidComponents. Esto puede ser más complejo, ya que la API de androidComponents está diseñada para ser más estable y mantener la compatibilidad de los complementos por más tiempo. Consulta nuestras Recetas de Gradle para ver ejemplos.

• Actualiza los complementos de terceros: Es posible que algunos complementos de terceros aún dependan de interfaces o APIs que ya no se exponen. Migra a versiones de esos complementos que sean compatibles con AGP 9.0.

El cambio a las nuevas interfaces de DSL evita que los complementos y las secuencias de comandos de compilación de Gradle usen varias APIs obsoletas, incluidas las siguientes:

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

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

Si actualizas al AGP 9.0 y ves el siguiente mensaje de error, significa que tu proyecto aún hace referencia a algunos de los tipos antiguos:

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

Si te bloquean los complementos de terceros incompatibles, puedes inhabilitar y recuperar las implementaciones anteriores para el DSL, así como la API de variantes anterior. Mientras haces esto, las interfaces nuevas también están disponibles, y puedes actualizar tu propia lógica de compilación a la API nueva. Para inhabilitar esta opción, incluye esta línea en tu archivo gradle.properties:

android.newDsl=false

Como alternativa, para una migración más gradual, AGP 9.4 te permite inhabilitar módulos individuales. Para obtener más información, consulta Inhabilitación del módulo de la API de Variant.

Las clases anteriores se marcaron como obsoletas en AGP 9.0. Esto significa que los proyectos que inhabiliten la marca newDsl verán advertencias de baja, incluso en el propio bloque android.

También puedes comenzar a actualizar a las nuevas APIs antes de actualizar a AGP 9.0. Las nuevas interfaces están presentes en muchas versiones de AGP, por lo que puedes tener una combinación de interfaces nuevas y antiguas. En la documentación de referencia de la API de AGP, se muestra la plataforma de la API para cada versión de AGP y cuándo se agregó cada clase, método y campo.

Nos comunicaremos con los autores de los complementos de uso frecuente para ayudarlos a adaptar y lanzar complementos que sean totalmente compatibles con los nuevos modos, y seguiremos mejorando el Asistente de actualización del AGP en Android Studio para guiarte durante la migración.

Si detectas que faltan capacidades o funciones en el nuevo DSL o en la API de Variant, informa el problema lo antes posible.

Kotlin integrado

El complemento de Android para Gradle 9.0 presenta compatibilidad integrada con Kotlin y la habilita de forma predeterminada. Esto significa que ya no tienes que aplicar el complemento org.jetbrains.kotlin.android (o kotlin-android) en tus archivos de compilación para compilar archivos de origen de Kotlin. Esto simplifica la integración de Kotlin con el AGP, evita el uso de APIs obsoletas y, en algunos casos, mejora el rendimiento.

Por lo tanto, cuando actualices tu proyecto a AGP 9.0, también deberás migrar a Kotlin integrado o inhabilitar la opción.

También puedes inhabilitar de forma selectiva la compatibilidad integrada con Kotlin para los subproyectos de Gradle que no tengan fuentes de Kotlin.

Dependencia del entorno de ejecución en el complemento de Gradle para Kotlin

Para proporcionar compatibilidad integrada con Kotlin, el complemento de Android para Gradle 9.0 ahora tiene una dependencia de tiempo de ejecución del complemento de Kotlin para Gradle (KGP) 2.2.10. Eso significa que ya no tienes que declarar una versión de KGP y, si usas una versión de KGP anterior a la 2.2.10, Gradle actualizará automáticamente tu versión de KGP a la 2.2.10. Del mismo modo, si usas una versión de KSP anterior a la 2.2.10-2.0.2, el AGP la actualizará a la 2.2.10-2.0.2 para que coincida con la versión de KGP.

Actualiza a una versión más reciente del KGP

Para usar una versión posterior de KGP o KSP, agrega lo siguiente a tu archivo de compilación de nivel superior:

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

Cambia a una versión inferior del KGP

Solo puedes cambiar a una versión anterior del KGP si inhabilitaste Kotlin integrado. Esto se debe a que el AGP 9.0 habilita Kotlin integrado de forma predeterminada, y Kotlin integrado requiere KGP 2.2.10 o una versión posterior.

Para usar una versión anterior de KGP o KSP, declara esa versión en tu archivo de compilación de nivel superior con una declaración de versión estricta:

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

Ten en cuenta que la versión mínima del KGP a la que puedes cambiar es la 2.0.0.

Compatibilidad del IDE con los dispositivos de prueba

El AGP 9.0 ofrece compatibilidad total con el IDE de Android Studio para los dispositivos de prueba.

Complemento de biblioteca fusionada

El complemento de biblioteca fusionada (versión preliminar) te permite publicar varias bibliotecas como un solo AAR de biblioteca de Android. Esto puede facilitar que tus usuarios dependan de tus artefactos publicados.

Para obtener información sobre cómo comenzar, consulta Cómo publicar varias bibliotecas de Android como una sola con Fused Library.

Cambios en el comportamiento

El complemento de Android para Gradle 9.0 tiene los siguientes comportamientos nuevos:

AGP 9.0 incluye actualizaciones de los siguientes valores predeterminados de las propiedades de Gradle. Esto te da la opción de conservar el comportamiento de AGP 8.13 cuando actualices:

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

android {
  buildFeatures {
    resValues = true
  }
}

android {
  buildFeatures {
    shaders = true
  }
}

Funciones quitadas

El complemento de Android para Gradle 9.0 quita las siguientes funciones:

• Compatibilidad con apps para Wear OS incorporadas
  AGP 9.0 quita la compatibilidad con la incorporación de apps para Wear OS, que ya no se admite en Play. Esto incluye quitar los parámetros de configuración de wearApp y el DSL de AndroidSourceSet.wearAppConfigurationName. Consulta Distribuye a Wear OS para obtener información sobre cómo publicar tu app en Wear OS.
• androidDependencies y sourceSets informan una tarea
• Compatibilidad con APKs divididos por densidad
  El AGP 9.0 quita la compatibilidad para crear APKs divididos según la densidad de la pantalla. Se quitaron la funcionalidad y las APIs relacionadas. Para dividir los APKs según la densidad de la pantalla con AGP 9.0 o versiones posteriores, usa paquetes de aplicación.

DSL modificada

El complemento de Android para Gradle 9.0 tiene los siguientes cambios rotundos en el DSL:

• Se quitó la parametrización de CommonExtension.

  En sí, este es solo un cambio rotundo a nivel de la fuente para ayudar a evitar futuros cambios rotundos a nivel de la fuente, pero también significa que los métodos de bloque deben pasar de CommonExtension a ApplicationExtension, LibraryExtension, DynamicFeatureExtension y TestExtension.

  Cuando actualices tu proyecto a AGP 9.0, refactoriza el código del complemento de Gradle que usa esos parámetros o los métodos de bloque. Por ejemplo, el siguiente complemento se actualiza para quitar el parámetro de tipo y no depender de los métodos de bloque quitados:

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

  En el caso de los complementos que se orientan a un rango de versiones del AGP, el uso directo del método get es compatible con el objeto binario de las versiones del AGP anteriores a la 9.0.

Se quitó el DSL

El complemento de Android para Gradle 9.0 quita lo siguiente:

• AndroidSourceSet.jni, porque no funcionaba.

• AndroidSourceSet.wearAppConfigurationName, ya que se relaciona con la compatibilidad con la app para Wear OS incorporada que se quitó.

• BuildType.isRenderscriptDebuggable, porque no funcionaba.

• DependencyVariantSelection. Se reemplaza por DependencySelection, que se expone como kotlin.android.localDependencySelection.

• Installation.installOptions(String): Se reemplaza por la propiedad mutable de Installation.installOptions.

• El bloque experimental, pero nunca estabilizado, PostProcessing.

• ProductFlavor.setDimension, que se reemplaza por la propiedad dimension

• LanguageSplitOptions, que solo era útil para Google Play Instant, que ya no está disponible.

• DensitySplit, porque la función ya no es compatible. El reemplazo consiste en usar paquetes de aplicaciones.

APIs que se quitaron

El complemento de Android para Gradle 9.0 quita lo siguiente:

• AndroidComponentsExtension.finalizeDSl. Se reemplaza por finalizeDsl

• Component.transformClassesWith. Se reemplaza por Instrumentation.transformClassesWith

• Component.setAsmFramesComputationMode. Se reemplaza por Instrumentation.setAsmFramesComputationMode

• ComponentBuilder.enabled. Se reemplaza por ComponentBuilder.enable.

• DependenciesInfoBuilder.includedInApk. Se reemplaza por includeInApk

• DependenciesInfoBuilder.includedInBundle. Se reemplaza por includeInBundle

• GeneratesApk.targetSdkVersion. Se reemplaza por targetSdk

• Variant.minSdkVersion. Se reemplaza por minSdk

• Variant.maxSdkVersion. Se reemplaza por maxSdk

• Variant.targetSdkVersion. Se reemplaza por targetSdk

• Variant.unitTest, ya que no se aplicaba al complemento com.android.test. unitTest está disponible en los subtipos de VariantBuilder que extienden HasUnitTest.

• VariantBuilder.targetSdk y targetSdkPreview, ya que no eran significativos en las bibliotecas En su lugar, usa GeneratesApkBuilder.targetSdk o GeneratesApkBuilder.targetSdkPreview.

• VariantBuilder.enableUnitTest, ya que no se aplicaba al complemento com.android.test. enableUnitTest está disponible en los subtipos de VariantBuilder que extienden HasUnitTestBuilder.

• Se quitó VariantBuilder.unitTestEnabled para dar lugar a enableUnitTest, que tiene un nombre más coherente, en los subtipos VariantBuilder que extienden HasUnitTestBuilder.

• VariantOutput.enable. Se reemplaza por enabled

• Los objetos FeaturePlugin y FeatureExtension que dejaron de estar disponibles y se inhabilitaron

• Las APIs de BaseExtension.registerTransform obsoletas e inhabilitadas, que solo se mantuvieron para permitir la compilación con la versión más reciente de AGP mientras se orientaban a la ejecución en AGP 4.2 o versiones anteriores.

Se quitaron las propiedades de Gradle

Las siguientes propiedades de Gradle se agregaron inicialmente como formas de inhabilitar de manera global las funciones que estaban habilitadas de forma predeterminada.

Estas funciones se inhabilitaron de forma predeterminada desde el AGP 8.0 o versiones anteriores. Habilita estas funciones solo en los subproyectos que las usen para obtener una compilación más eficiente.

android {
  buildFeatures {
    aidl = true
  }
}

android {
  buildFeatures {
    renderScript = true
  }
}

Propiedades de Gradle aplicadas de forma forzosa

AGP 9.0 arroja un error si configuras las siguientes propiedades de Gradle.

El Asistente de actualización del complemento de Android para Gradle no actualizará los proyectos a AGP 9.0 que usen estas propiedades.

Cambios en R8

Los siguientes cambios de R8 se incluyen en AGP 9.0.0.

Nueva opción de configuración -processkotlinnullchecks

Agregamos la nueva opción de R8 -processkotlinnullchecks para configurar R8 de modo que procese las verificaciones nulas de Kotlin. La opción toma un argumento obligatorio que debe ser uno de los siguientes tres valores: keep, remove_message y remove. La opción procesa las siguientes verificaciones de nulos que agrega el compilador de 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);
}

Los valores de las opciones, ordenados de menor a mayor, tienen el siguiente efecto:

• keep no cambia las verificaciones.
• remove_message reescribe cada llamada de método de verificación en una llamada a getClass() en el primer argumento de la llamada (lo que mantiene la verificación de nulos, pero sin ningún mensaje).
• remove quita las verificaciones por completo.

De forma predeterminada, R8 usa remove_message. Cualquier especificación de -processkotlinnullchecks anulará eso. Si se especifica varias veces, se usa el valor más fuerte.

Deja de propagar información de conservación a métodos complementarios

Cuando las reglas de conservación coinciden con los métodos de interfaz que están sujetos a la expansión de sintaxis, R8 transfería internamente los bits de inhabilitación de optimización y de inhabilitación de reducción a los métodos complementarios sintetizados.

A partir de AGP 9.0, las reglas de conservación ya no se aplican a los métodos complementarios. Esto es coherente con el hecho de que las reglas de conservación no se aplican a otros campos, métodos o clases sintetizados por el compilador.

Cuando se transferían los bits disallow optimization y disallow shrinking a los métodos complementarios, se admitía el siguiente caso de uso:

1. Compila una biblioteca con métodos de interfaz default/static/private en DEX con minSdk < 24 y reglas que conserven los métodos de interfaz.
2. Compila una app con la biblioteca en la ruta de clase y -applymapping.
3. Combina la app y la biblioteca.

Ten en cuenta que esto solo funciona con -applymapping, ya que el bit disallow obfuscation no se transfiere a los métodos complementarios, es decir, las clases complementarias generadas a partir del paso 1 tendrían nombres de métodos ofuscados.

En el futuro, este caso de uso ya no se admitirá para minSdk < 24. La solución alternativa es hacer lo siguiente:

1. Aplica la expansión de sintaxis a la biblioteca con métodos de interfaz default/static/private para clasificar archivos con minSdk < 24.
2. Compila el artefacto con expansión de sintaxis usando R8 y reglas que mantengan los métodos de interfaz en las clases complementarias.
3. Compila la app con la biblioteca en la ruta de clase.
4. Combina la app y el artefacto sin sintaxis enriquecida.

Otro efecto secundario de esto es que ya no es posible mantener los atributos de clase interna y método envolvente para las clases anónimas y locales dentro de los métodos complementarios de interfaz.

Cambia el archivo de origen emitido predeterminado a r8-map-id-<MAP_ID>

Este cambio se encuentra en el AGP a partir de la versión 8.12.0.

El atributo de archivo de origen emitido predeterminado para una clase cambia de SourceFile a r8-map-id-<MAP_ID> cuando se requiere un nuevo seguimiento (es decir, cuando se habilita la optimización o la ofuscación).

Dado un seguimiento de pila ofuscado, el nuevo atributo de archivo de origen permite extraer el ID del archivo de asignación que se requiere para el rastreo, que se puede usar para admitir el rastreo automatizado de seguimientos de pila en Logcat.

Si se usa un atributo de archivo de origen personalizado (-renamesourcefileattribute), este atributo sigue teniendo prioridad.

En el modo de compatibilidad con ProGuard (cuando gradle.properties contiene android.enableR8.fullMode=false), emitir un atributo de archivo de origen de r8-map-id-<MAP_ID> solo tiene efecto si no se conserva el atributo SourceFile. Las apps que usan el modo de compatibilidad de ProGuard y quieren incluir el ID del archivo de asignación en sus seguimientos de pila deben quitar -keepattributes SourceFile (o migrar al modo completo de R8).

El ID de mapa que se usa en r8-map-id-<MAP_ID> es el hash de mapa completo y no un prefijo de 7 caracteres del hash de mapa que se usaba anteriormente.

Habilita el uso de nombres sintéticos minimizados en la expansión de sintaxis de L8

El nombre de las clases sintéticas que genera D8 suele contener la cadena secundaria $$ExternalSynthetic, que indica que se trata de un elemento sintético generado por D8. Además, el nombre del elemento sintético también codifica el tipo de elemento sintético (por ejemplo, Backport, Lambda). Esto tiene un impacto negativo en el tamaño del DEX resultante, ya que los nombres de las clases ocupan más espacio en el grupo de cadenas.

El AGP 9.0 configura L8 (expansión de sintaxis de la biblioteca principal) para que el archivo DEX que contiene todas las clases j$ use un nuevo formato de nombre de clase abreviado para las clases sintéticas. El nombre de la clase nueva usa un ID numérico (por ejemplo, $1).

Quitar la compatibilidad con -addconfigurationdebugging

AGP 9.0 quita la compatibilidad con -addconfigurationdebugging. Ahora, el compilador informa una advertencia si se usa la marca.

Elimina la compatibilidad para generar reglas de L8 desde D8/R8

Este cambio solo es relevante para los desarrolladores que usan la línea de comandos o las APIs de D8/R8 directamente.

R8 9.0 quita la compatibilidad para generar reglas de conservación para L8 desde D8 y R8. En su lugar, debes usar TraceReferences para este propósito.

Específicamente, se quitan los métodos D8Command.builder.setDesugaredLibraryKeepRuleConsumer y R8Command.Builder.setDesugaredLibraryKeepRuleConsumer, y se quita la compatibilidad con --desugared-lib-pg-conf-output de las opciones de línea de comandos de D8 y R8.

Errores corregidos

Complemento de Android para Gradle 9.0.0