Se usó la API de Cloud Translation para traducir esta página.

Cómo agregar dependencias de compilación

El sistema de compilación de Gradle en Android Studio te permite incluir objetos binarios externos o 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 opciones de configuración que son específicos del complemento de Android para Gradle (AGP). Para obtener una guía conceptual más detallada sobre las dependencias de Gradle, consulta la Guía de Gradle para la administración de dependencias. Sin embargo, recuerda que tu proyecto de Android solo debe usar las opciones 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, que es el método que usan los proyectos nuevos de forma predeterminada. En esta sección, se describen los tipos de configuraciones más comunes que se usan para 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 tienes dependencias de compilación configuradas sin catálogos de versiones y tienes un proyecto de varios módulos, te recomendamos migrar.

Si deseas obtener orientación para agregar y administrar dependencias nativas (no comunes), consulta Dependencias nativas.

En el siguiente ejemplo, agregamos una dependencia binaria remota (la biblioteca de Macrobenchmark de Jetpack), 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:

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 de la vista Project o 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 solo catálogo de versiones, te recomendamos que mantengas el valor predeterminado de "libs".
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 familias de bibliotecas y sus versiones. Puedes incluir una BoM en tu catálogo de versiones y archivos de compilación, y permitir que administre esas versiones por ti. Consulta Cómo usar la lista de materiales para obtener más detalles.
Agrega una referencia al alias de dependencia a la secuencia de comandos de compilación de los módulos que requieren la dependencia. Convierte los guiones bajos y los guiones del alias en puntos cuando hagas referencia a él desde una secuencia de comandos de compilación. Nuestra secuencia de comandos de compilación a nivel del 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 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 bibliotecas 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 muestra 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 informa a Gradle que no quieres que el módulo filtre la dependencia a otros módulos en el tiempo de la compilación. Es decir, la dependencia no estará disponible para otros módulos que dependan del módulo actual. El uso de esta configuración de dependencia, en lugar de `api`, puede generar mejoras significativas en 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 manera 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 necesites exportar de forma transitiva a otros consumidores ascendentes. Si una dependencia `api` cambia su API externa, Gradle vuelve 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 significativamente el tiempo de compilación. A menos que quieras exponer la API de una 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 (pero no al resultado). 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 de tiempo de compilación (que suelen usarse para generar código, pero que a menudo no se incluyen en el resultado de la 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 compilación. Esto rara vez se usa en Android, pero se usa con frecuencia en aplicaciones de servidor para proporcionar implementaciones de registro. Por ejemplo, una biblioteca podría usar una API de registro que no incluya una implementación. Los consumidores de esa biblioteca podrían agregarla como una depencia de `implementation` e incluir una depencia de `runtimeOnly` para que la implementación de registro real la use.
`ksp kapt annotationProcessor`	Estas 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 debes escribir. Para agregar una dependencia de este tipo, debes agregarla a la ruta de clase del procesador de anotaciones con las configuraciones `ksp`, `kapt` o `annotationProcessor`. El uso de estas configuraciones mejora el rendimiento de la compilación, ya que se separa la ruta de clase de compilación de la ruta de clase del procesador de anotaciones. Si Gradle encuentra procesadores de anotaciones en la ruta de clase de la compilación, desactivará la elusión de compilación, lo que afectará 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 es ejecutado por el compilador de Kotlin. `kapt` y `apt` son herramientas independientes que procesan anotaciones antes de que se ejecuten los compiladores de Kotlin o Java. Cuando decidas qué configuración usar, ten en cuenta lo siguiente: Si un procesador está disponible como procesador de símbolos de Kotlin, úsalo como una dependencia de `ksp`. Consulta Cómo migrar de kapt a KSP para obtener detalles sobre el uso de los 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 fuente de Java), usa `kapt` para incluirlo. Si tu proyecto solo usa fuentes de Java, usa `annotationProcessor` para incluirlas. 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 contienen un archivo `lint.jar` ejecutarán automáticamente las verificaciones definidas en ese archivo `lint.jar`. No es necesario que agregues una dependencia `lintChecks` explícita. Esto te permite definir bibliotecas y verificaciones de lint asociadas en una sola dependencia, lo que garantiza que tus verificaciones 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 quieres declarar una dependencia solo para un conjunto de fuentes de una variante de compilación o un conjunto de fuentes de prueba específicos, usa mayúsculas para el nombre de la configuración y agrégale un prefijo con el nombre de la variante de compilación o el conjunto de fuentes de prueba.

Por ejemplo, si quieres agregar una dependencia binaria remota solo a tu variante de producto "gratuito" 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 un tipo de producto y un tipo de compilación, deberás inicializar el nombre de la 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.6.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.6.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:

LIB_A
LIB_D
LIB_B
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 la biblioteca que se compilan en la app. Cuando subes tu app, Play Console inspecciona estos metadatos para proporcionar alertas sobre problemas conocidos con los SDKs y las 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 firmas de tu app de lanzamiento. Recomendamos conservar este archivo de dependencias para 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 marcan 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. A continuación, se muestra 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 una dependencia en 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 un atajo para 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 la 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 versión del complemento en la ruta de acceso de 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 se aplique. Agregar apply false le indica a Gradle que tome nota de la versión del complemento, pero que 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 por 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 forma explícita en la secuencia de comandos de compilación a nivel del módulo y dejar la secuencia de comandos de compilación a nivel del proyecto vacía:

Kotlin

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

Groovy

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