Cómo agregar dependencias de compilación

El sistema de compilación de Gradle en Android Studio te permite incluir objetos binarios externos y otros módulos de biblioteca a tu compilación como dependencias. Las dependencias pueden ubicarse en tu máquina o en un repositorio remoto, y cualquier dependencia transitiva que estas declaren se incluirá automáticamente. En esta página, se describe cómo usar las dependencias con tu proyecto de Android, incluidos los detalles sobre los comportamientos y las configuraciones que son específicos del complemento de Android para Gradle (AGP). A fin de obtener una guía conceptual más detallada sobre las dependencias de Gradle, también deberías consultar la Guía de Gradle para la administración de dependencias. Sin embargo, recuerda que tu proyecto de Android solo debe usar los parámetros de configuración de dependencias que se definen en esta página.

Cómo agregar una dependencia de biblioteca o complemento

La mejor manera de agregar y administrar dependencias de compilación es usar catálogos de versiones, el método que usan los proyectos nuevos de forma predeterminada. En esta sección, se abordan los tipos de configuración más comunes que se usan en proyectos de Android. Consulta la documentación de Gradle para obtener más opciones. Para ver un ejemplo de una app que usa catálogos de versiones, consulta Ahora en Android. Si ya configuraste dependencias de compilación sin catálogos de versiones y tienes un proyecto de varios módulos, te recomendamos que migres.

Para obtener orientación sobre cómo agregar y administrar dependencias nativas (poco común), consulta Dependencias nativas.

En el siguiente ejemplo, agregamos una dependencia binaria remota (la biblioteca de Jetpack Macrobenchmark), una dependencia de módulo de biblioteca local (myLibrary) y una dependencia de complemento (el complemento de Android para Gradle) a nuestro proyecto. Estos son los pasos generales para agregar estas dependencias a tu proyecto:

  1. Agrega un alias para la versión de la dependencia que deseas en la sección [versions] del archivo del catálogo de versiones, llamada libs.versions.toml (en el directorio gradle en la vista Project o en Gradle Scripts en la vista Android):

    [versions]
    agp = "8.3.0"
    androidx-macro-benchmark = "1.2.2"
    my-library = "1.4"
    
    [libraries]
    ...
    
    [plugins]
    ...
    

    Los alias pueden incluir guiones o guiones bajos. Estos alias generan valores anidados a los que puedes hacer referencia en las secuencias de comandos de compilación. Las referencias comienzan con el nombre del catálogo, la parte libs de libs.versions.toml. Cuando uses un catálogo de una sola versión, te recomendamos que mantengas el valor predeterminado de "libs".

  2. Agrega un alias para la dependencia en las secciones [libraries] (para objetos binarios remotos o módulos de bibliotecas locales) o [plugins] (para complementos) del archivo libs.versions.toml.

    [versions]
    ...
    
    [libraries]
    androidx-benchmark-macro = { group = "androidx.benchmark", name = "benchmark-macro-junit4", version.ref = "androidx-macro-benchmark" }
    my-library = { group = "com.myapplication", name = "mylibrary", version.ref = "my-library" }
    
    [plugins]
    androidApplication = { id = "com.android.application", version.ref = "agp" }
    

    Algunas bibliotecas están disponibles en una lista de materiales (BoM) publicada que agrupa las familias de bibliotecas y sus versiones. Puedes incluir una BoM en tu catálogo de versiones y archivos de compilación y dejar que administre esas versiones por ti. Consulta Cómo usar la lista de materiales para obtener más detalles.

  3. Agrega una referencia al alias de la dependencia a la secuencia de comandos de compilación de los módulos que requieren la dependencia. Convierte los guiones bajos y guiones bajos en puntos cuando hagas referencia a él desde una secuencia de comandos de compilación. Nuestra secuencia de comandos de compilación a nivel de módulo se vería de la siguiente manera:

    Kotlin

    plugins {
      alias(libs.plugins.androidApplication)
    }
    
    dependencies {
      implementation(libs.androidx.benchmark.macro)
      implementation(libs.my.library)
    }
    

    Groovy

    plugins {
      alias 'libs.plugins.androidApplication'
    }
    
    dependencies {
      implementation libs.androidx.benchmark.macro
      implementation libs.my.library
    }
    

    Las referencias de complementos incluyen plugins después del nombre del catálogo, y las referencias de la versión incluyen versions después del nombre del catálogo (las referencias de versión son poco comunes; consulta Dependencias con los mismos números de versión para ver ejemplos de referencias de versión). Las referencias de biblioteca no incluyen un calificador libraries, por lo que no puedes usar versions ni plugins al comienzo de un alias de biblioteca.

Configurar dependencias

Dentro del bloque dependencies, puedes declarar una dependencia de biblioteca con una de las diferentes configuraciones de dependencias (como implementation, que se mostró antes). La configuración de cada dependencia le proporciona a Gradle diferentes instrucciones para usarla. En la siguiente tabla, se describe cada una de las configuraciones que puedes usar para una dependencia en tu proyecto de Android.

Configuración Comportamiento
implementation Gradle agrega la dependencia a la ruta de clase de la compilación y la empaqueta en el resultado de la compilación. Cuando tu módulo configura una dependencia implementation, se le indica a Gradle que no quieres que el módulo filtre la dependencia a otros módulos en el tiempo de compilación. Es decir, la dependencia no se pone a disposición de otros módulos que dependen del módulo actual.

El uso de esta configuración de dependencia en lugar de api puede mejorar significativamente el tiempo de compilación, ya que reduce la cantidad de módulos que el sistema de compilación debe volver a compilar. Por ejemplo, si una dependencia implementation cambia su API, Gradle solo volverá a compilar esa dependencia y los módulos que dependen de esta directamente. La mayoría de los módulos de prueba y de apps deben usar esta configuración.

api Gradle agrega la dependencia a la ruta de clase y al resultado de la compilación. Cuando un módulo incluye una dependencia api, se le indica a Gradle que el módulo quiere exportar de forma transitiva esa dependencia a otros módulos, de modo que esté disponible para ellos tanto en el tiempo de ejecución como en el de compilación.

Usa esta configuración con precaución y solo con las dependencias que necesitas exportar de forma transitiva a otros consumidores ascendentes. Si una dependencia api cambia su API externa, Gradle volverá a compilar todos los módulos que tengan acceso a esa dependencia en el tiempo de compilación. Tener una gran cantidad de dependencias api puede aumentar en gran medida el tiempo de compilación. A menos que quieras exponer una API de dependencia en un módulo separado, los módulos de biblioteca deberían usar dependencias implementation.

compileOnly Gradle solo agrega la dependencia a la ruta de clase de la compilación (es decir, no se agrega al resultado de la compilación). lo que resulta útil cuando creas un módulo de Android y necesitas la dependencia durante la compilación. Sin embargo, tenerla presente durante el tiempo de ejecución es opcional. Por ejemplo, si dependes de una biblioteca que solo incluye anotaciones en tiempo de compilación (por lo general, se usan para generar código, pero a menudo no se incluyen en el resultado de compilación), puedes marcar esa biblioteca como compileOnly.

Si usas esta configuración, entonces tu módulo de biblioteca debe incluir una condición de tiempo de ejecución para comprobar si la dependencia está disponible y, luego, cambiar de manera fluida su comportamiento a fin de que pueda funcionar en caso de que esta no se proporcione. De este modo, se reduce el tamaño de la app final, ya que no se agregan dependencias transitivas que no sean fundamentales.

Nota: No puedes usar la configuración compileOnly con dependencias de Android ARchive (AAR).

runtimeOnly Gradle solo agrega la dependencia al resultado de la compilación para usar durante el tiempo de ejecución. Es decir, esta no se agrega a la ruta de clase de la compilación. Es poco frecuente en Android, pero se suele usar en aplicaciones de servidor para proporcionar implementaciones de registros. Por ejemplo, una biblioteca podría usar una API de Logging que no incluya una implementación. Los consumidores de esa biblioteca podrían agregarla como una dependencia implementation e incluir una dependencia runtimeOnly para que la use la implementación real del registro.
ksp
kapt
annotationProcessor

Esas configuraciones proporcionan bibliotecas que procesan anotaciones y otros símbolos en tu código antes de que se compile. Por lo general, validan tu código o generan código adicional, lo que reduce el código que tienes que escribir.

Para agregar una dependencia de este tipo, debes hacerlo a la ruta de clase del procesador de anotaciones mediante las configuraciones ksp, kapt o annotationProcessor. El uso de esta configuración mejora el rendimiento de la compilación porque separa la ruta de clase de la compilación de la del procesador de anotaciones. Si Gradle encuentra procesadores de anotaciones en la ruta de clase de la compilación, desactiva la elusión de compilación, lo que afecta negativamente el tiempo de compilación (a partir de la versión 5.0 de Gradle, se ignoran los procesadores de anotaciones que se encuentran en la ruta de clase de la compilación).

El complemento de Android para Gradle entiende que una dependencia es un procesador de anotaciones si su archivo JAR contiene el siguiente archivo:

META-INF/services/javax.annotation.processing.Processor

Si el complemento detecta un procesador de anotaciones que está en la ruta de clase de la compilación, se producirá un error de compilación.

ksp es un procesador de símbolos de Kotlin y lo ejecuta el compilador de Kotlin.

kapt y apt son herramientas independientes que procesan las anotaciones antes de que se ejecuten los compiladores de Kotlin o Java.

Cuando decidas qué configuración usar, ten en cuenta lo siguiente:

  • Si hay un procesador disponible como procesador de símbolos de Kotlin, úsalo como dependencia ksp. Consulta Cómo migrar de kapt a ksp para obtener detalles sobre el uso de procesadores de símbolos de Kotlin.
  • Si el procesador no está disponible como procesador de símbolos de Kotlin, haz lo siguiente:
    • Si tu proyecto incluye código fuente de Kotlin (pero también puede incluir código de Java), usa kapt para incluirlo.
    • Si tu proyecto solo usa código fuente Java, usa annotationProcessor para incluirlo.

Para obtener más información sobre el uso de procesadores de anotaciones, consulta Cómo agregar procesadores de anotaciones.

lintChecks

Usa esta configuración para incluir una biblioteca que contenga comprobaciones de lint que quieras que Gradle ejecute cuando compiles tu proyecto de app para Android.

Ten en cuenta que los AAR que contengan un archivo lint.jar ejecutarán automáticamente verificaciones definidas en ese archivo lint.jar; no es necesario que agregues una dependencia lintChecks explícita. De esta manera, puedes definir bibliotecas y comprobaciones de lint asociadas en una sola dependencia, lo que garantiza que las comprobaciones se ejecuten cuando los consumidores usen tu biblioteca.

lintPublish Utiliza esta configuración en los proyectos de la biblioteca de Android para incluir comprobaciones de Lint que quieras que Gradle compile en un archivo lint.jar y empaquete en tu AAR. De esa forma, los proyectos que consumen tu AAR también aplican esas comprobaciones de Lint. Si anteriormente usabas la configuración de dependencia lintChecks para incluir comprobaciones de lint en el AAR publicado, deberás migrar esas dependencias a fin de usar la configuración lintPublish.

Kotlin

dependencies {
  // Executes lint checks from the ":checks" project at build time.
  lintChecks(project(":checks"))
  // Compiles lint checks from the ":checks-to-publish" into a
  // lint.jar file and publishes it to your Android library.
  lintPublish(project(":checks-to-publish"))
}

Groovy

dependencies {
  // Executes lint checks from the ':checks' project at build time.
  lintChecks project(':checks')
  // Compiles lint checks from the ':checks-to-publish' into a
  // lint.jar file and publishes it to your Android library.
  lintPublish project(':checks-to-publish')
}

Cómo configurar dependencias para una variante de compilación específica

Todas las configuraciones anteriores aplican dependencias a todas las variantes de compilación. Sin embargo, si deseas declarar una dependencia solo para un conjunto de orígenes de una variante de compilación específico o un conjunto de orígenes de prueba, debes escribir en mayúscula el nombre de la configuración y agregarle el nombre de la variante de compilación o del conjunto de fuentes de prueba como prefijo.

Por ejemplo, para agregar una dependencia binaria remota solo a tu variante de producto "gratis" con la configuración implementation, usa lo siguiente:

Kotlin

dependencies {
    freeImplementation("com.google.firebase:firebase-ads:21.5.1")
}

Groovy

dependencies {
    freeImplementation 'com.google.firebase:firebase-ads:21.5.1'
}

Sin embargo, si deseas agregar una dependencia para una variante que combina una variante de producto y un tipo de compilación, debes inicializar el nombre de configuración:

Kotlin

// Initializes a placeholder for the freeDebugImplementation dependency configuration.
val freeDebugImplementation by configurations.creating

dependencies {
    freeDebugImplementation(project(":free-support"))
}

Groovy

configurations {
    // Initializes a placeholder for the freeDebugImplementation dependency configuration.
    freeDebugImplementation {}
}

dependencies {
    freeDebugImplementation project(":free-support")
}

Las dependencias implementation que agregues en las pruebas instrumentadas y las locales tendrán el siguiente aspecto:

Kotlin

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation("junit:junit:4.12")

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation("androidx.test.espresso:espresso-core:3.5.1")
}

Groovy

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation 'junit:junit:4.12'

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.5.1'
}

Sin embargo, algunas opciones de configuración no son útiles en esta situación. Por ejemplo, como otros módulos no pueden depender de androidTest, verás la siguiente advertencia si usas la configuración androidTestApi:

WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with
'androidTestImplementation'.

Orden de las dependencias

El orden en el que enumeras tus dependencias indica la prioridad de cada una: la primera biblioteca tendrá mayor prioridad que la segunda, la segunda tendrá mayor prioridad que la tercera, y así sucesivamente. Este orden es importante en el caso de que se combinen los recursos o se combinen los elementos del manifiesto en tu app desde las bibliotecas.

Por ejemplo, si en tu proyecto se declara lo siguiente:

  • Hay una dependencia en LIB_A y LIB_B (en ese orden).
  • Además, LIB_A depende de LIB_C y LIB_D (en ese orden).
  • LIB_B también depende de LIB_C.

Luego, el orden de la dependencia única será el siguiente:

  1. LIB_A
  2. LIB_D
  3. LIB_B
  4. LIB_C

De esta manera, se garantiza que tanto LIB_A como LIB_B puedan anular a LIB_C; además, LIB_D sigue teniendo mayor prioridad que LIB_B porque LIB_A (que depende de esta) tiene mayor prioridad que LIB_B.

Para descubrir cómo se fusionan los manifiestos de diferentes fuentes o dependencias de proyectos, consulta Cómo fusionar varios archivos de manifiestos.

Información de la dependencia de Play Console

Cuando compilas tu app, AGP incluye metadatos que describen las dependencias de biblioteca que se compilan en tu app. Cuando subes tu app, Play Console inspecciona estos metadatos para proporcionar alertas de problemas conocidos con SDKs y dependencias que usa tu app y, en algunos casos, proporcionar comentarios prácticos para resolver esos problemas.

Los datos se comprimen, se encriptan con una clave de firma de Google Play y se almacenan en el bloque de firma de tu app de lanzamiento. Te recomendamos que conserves este archivo de dependencias para brindar una experiencia del usuario segura y positiva. Para inhabilitar esta opción, incluye el siguiente bloque dependenciesInfo en el archivo build.gradle.kts de tu módulo.

android {
    dependenciesInfo {
        // Disables dependency metadata when building APKs.
        includeInApk = false
        // Disables dependency metadata when building Android App Bundles.
        includeInBundle = false
    }
}

Para obtener más información sobre nuestras políticas y posibles problemas con las dependencias, consulta nuestra página de asistencia para usar los SDK de terceros en tu app.

Estadísticas del SDK

Android Studio muestra advertencias de lint en el archivo del catálogo de versiones y en el diálogo Project Structure para los SDKs públicos en el Índice SDK de Google Play cuando se aplican los siguientes problemas:

  • Los autores marcaron los SDKs como desactualizados.
  • Los SDKs incumplen las políticas de Play.

Las advertencias son indicadores de que debes actualizar esas dependencias, ya que usar versiones desactualizadas podría impedir que publiques contenido en Google Play Console en el futuro.

Cómo agregar dependencias de compilación sin catálogos de versiones

Recomendamos usar catálogos de versiones para agregar y administrar dependencias, pero es posible que los proyectos simples no los necesiten. El siguiente es un ejemplo de un archivo de compilación que no usa catálogos de versiones:

Kotlin

plugins {
    id("com.android.application")
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation("com.example.android:app-magic:12.3")
    // Dependency on a local library module
    implementation(project(":mylibrary"))
}

Groovy

plugins {
    id 'com.android.application'
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation 'com.example.android:app-magic:12.3'
    // Dependency on a local library module
    implementation project(':mylibrary')
}

Este archivo de compilación declara que depende de la versión 12.3 de la biblioteca "app-magic", dentro del grupo de espacios de nombres "com.example.android". La declaración de dependencia binaria remota es una abreviatura de lo siguiente:

Kotlin

implementation(group = "com.example.android", name = "app-magic", version = "12.3")

Groovy

implementation group: 'com.example.android', name: 'app-magic', version: '12.3'

El archivo de compilación también declara una dependencia en un módulo de biblioteca de Android llamado "mylibrary"; este nombre debe coincidir con el nombre de biblioteca definido con include: en tu archivo settings.gradle.kts. Cuando compilas tu app, el sistema de compilación compila el módulo de biblioteca y empaqueta el contenido compilado resultante en la app.

El archivo de compilación también declara una dependencia en el complemento de Android para Gradle (com.application.android). Si tienes varios módulos que usan el mismo complemento, solo puedes tener una única versión del complemento en la ruta de clase de la compilación en todos los módulos. En lugar de especificar la versión en cada una de las secuencias de comandos de compilación del módulo, debes incluir la dependencia del complemento en la secuencia de comandos de compilación raíz con la versión y, luego, indicar que no la apliques. Agregar apply false le indica a Gradle que anota la versión del complemento, pero no la use en la compilación raíz. Por lo general, la secuencia de comandos de compilación raíz está vacía, excepto este bloque plugins.

Kotlin

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
}

Groovy

plugins {
    id ‘com.android.application’ version ‘8.3.0-rc02’ apply false
}

Si tienes un proyecto de un solo módulo, puedes especificar la versión de manera explícita en la secuencia de comandos de compilación de nivel de módulo y dejar la secuencia de comandos de compilación de nivel de proyecto vacía:

Kotlin

plugins {
    id("com.android.application") version "8.3.0"
}

Groovy

plugins {
    id 'com.android.application' version '8.3.0-rc02'
}