Qué es Gradle en Android Studio y cómo se configura
¿Qué es Gradle en Android Studio?
Gradle es una herramienta de automatización de la construcción (en inglés, build), y es la que usa Android Studio para convertir tu proyecto en una app que se puede instalar. Construir una app Android es mucho más que compilar: hay que descargar las librerías que usas, compilar el código Kotlin o Java, juntar imágenes y textos, y empaquetarlo todo en un APK firmado que se pueda instalar. Gradle hace todos esos pasos por ti, siempre en el mismo orden.
Piénsalo como un mueble de montar. Los ficheros de Gradle son la hoja de instrucciones: qué piezas lleva (las dependencias, es decir, las librerías), de qué modelo es cada una (las versiones) y en qué orden se monta. Gradle es quien lo monta siguiendo la hoja al pie de la letra cada vez. El símil se queda corto en una cosa: quien monta un mueble no se acuerda de lo que ya montó, y Gradle sí; si nada ha cambiado, se salta los pasos que ya hizo.
Gradle por sí solo no sabe nada de Android. Lo que le enseña a construir apps es el Android Gradle Plugin (AGP), un complemento de Google. La versión estable actual es la 9.5, que pide Gradle 9.6.0 o superior y JDK 17.
Los ficheros de Gradle Scripts
Con la vista Android del panel de proyecto, Android Studio agrupa todos los ficheros de Gradle en Gradle Scripts. Así se veía en 2018, cuando escribí la primera versión de este artículo:
Hoy la lista es casi la misma, pero los ficheros de construcción terminan en .kts y aparece uno nuevo, libs.versions.toml:
| Fichero | Para qué sirve |
|---|---|
settings.gradle.kts |
Dice qué módulos forman el proyecto (include(":app")) y de qué repositorios se descargan plugins y librerías |
build.gradle.kts (Project) |
El de nivel de proyecto. Declara los plugins que usan los módulos, con su versión, pero sin aplicarlos |
build.gradle.kts (Module :app) |
El de nivel de módulo. Aquí va la configuración de Android y las dependencias de ese módulo. Es el que más vas a tocar |
gradle/libs.versions.toml |
El catálogo de versiones: todas las librerías y plugins con su versión, en un solo sitio |
gradle.properties |
Ajustes de Gradle para todo el proyecto, como la memoria máxima que puede usar |
gradle/wrapper/gradle-wrapper.properties |
Qué versión de Gradle usa el proyecto (lo verás en la sección del wrapper) |
local.properties |
Ajustes de tu equipo, sobre todo la ruta al Android SDK (sdk.dir). No se comparte |
proguard-rules.pro |
Reglas para reducir y ofuscar el código en la versión de publicación |
Gradle de proyecto y Gradle de módulo
La principal diferencia entre los dos build.gradle.kts:
- El de proyecto es la configuración global. Hoy suele tener solo un bloque
pluginsque declara qué plugins existen y en qué versión, conapply falsepara no aplicarlos a la raíz. - El de módulo es donde aplicas los plugins, configuras Android y añades tus dependencias y herramientas de terceros. Un proyecto puede tener varios módulos (la app, una librería…), y cada uno tiene el suyo.
build.gradle.kts leen con libs..Cómo es hoy un build.gradle.kts de módulo
Desde Android Studio Giraffe, los proyectos nuevos usan Kotlin DSL: los ficheros se escriben en Kotlin y terminan en .gradle.kts. Android Studio te autocompleta y te marca los errores mientras escribes, algo que con Groovy, el lenguaje de antes, funcionaba peor.
Este es un app/build.gradle.kts mínimo, basado en el ejemplo de la documentación oficial de Android:
plugins {
alias(libs.plugins.android.application)
}
android {
namespace = "com.rubentejera.holamundo"
compileSdk = 36
defaultConfig {
applicationId = "com.rubentejera.holamundo"
minSdk = 23
targetSdk = 36
versionCode = 1
versionName = "1.0"
}
buildTypes {
getByName("release") {
isMinifyEnabled = true
proguardFiles(
getDefaultProguardFile("proguard-android-optimize.txt"),
"proguard-rules.pro"
)
}
}
}
dependencies {
implementation(libs.androidx.appcompat)
}
Parámetros del Gradle de módulo
namespace: el paquete de tu código. Android lo usa para generar la claseR, con la que accedes a los recursos.applicationId: el identificador único de la app en Google Play y en el móvil. Suele coincidir con elnamespace, pero no tiene por qué.compileSdk: qué versión del Android SDK se usa para compilar. Decide qué funciones de Android puedes usar en tu código. Si es antigua, no podrás usar las más nuevas. Afecta en tiempo de compilación, no en tiempo de ejecución. Se recomienda usar la más reciente; AGP 9.5 admite hasta la API 37.minSdk: la versión mínima de Android en la que se puede instalar tu app. Es la que eliges en el asistente al crear el proyecto, y puedes cambiarla después aquí. Cuanto más baja, más móviles llegas a cubrir, pero más casos especiales tendrás que tratar en el código. Si usas una librería cuyominSdkes mayor que el tuyo, tendrás que subir el tuyo para poder usarla. Para elegirla te ayuda la lista de versiones de Android.targetSdk: la versión de Android para la que has probado tu app. Si el móvil tiene una versión más nueva, Android ejecuta tu app imitando el comportamiento de la versión que indicas aquí, para no romperla. Google Play exige untargetSdkmínimo para publicar, y ese mínimo va subiendo.versionCode: el número interno de versión. Cada vez que publiques una actualización tiene que ser mayor que el anterior.versionName: el nombre de la versión que ve el usuario, por ejemplo"1.0".isMinifyEnabled: activa la reducción de código (con R8) en la versión de publicación, para que la app ocupe menos.
De Groovy a Kotlin DSL: qué cambia
Así era el Gradle de módulo de mi Hola Mundo en 2018, escrito en Groovy:
apply plugin: 'com.android.application'
apply plugin: 'kotlin-android'
apply plugin: 'kotlin-android-extensions'
android {
compileSdkVersion 28
defaultConfig {
applicationId "com.rubentejera.holamundo"
minSdkVersion 19
targetSdkVersion 28
versionCode 1
versionName "1.0"
testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"
}
buildTypes {
release {
minifyEnabled false
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
}
}
}
Si tienes un proyecto así, estas son las diferencias:
Groovy (build.gradle, 2018)
apply plugin: 'com.android.application'compileSdkVersion 28minSdkVersion 19ytargetSdkVersion 28minifyEnabled false- Comillas simples:
'proguard-rules.pro' android.support.test.runner.AndroidJUnitRunner
Kotlin DSL (build.gradle.kts, hoy)
plugins { alias(libs.plugins.android.application) }compileSdk = 36minSdk = 23ytargetSdk = 36isMinifyEnabled = false- Siempre comillas dobles:
"proguard-rules.pro" androidx.test.runner.AndroidJUnitRunner
Las reglas generales: en Kotlin las asignaciones llevan =, las llamadas llevan paréntesis, las cadenas van entre comillas dobles y las propiedades booleanas empiezan por is (isMinifyEnabled, isDebuggable). Puedes migrar fichero a fichero: un proyecto admite tener unos en Groovy y otros en Kotlin a la vez.
Dos plugins de aquel fichero ya no se usan: kotlin-android sobra desde AGP 9.0 porque Kotlin viene integrado, y kotlin-android-extensions está obsoleto; para acceder a las vistas se usa view binding.
El paso de android.support.test a androidx.test viene de la antigua Support Library, que terminó en la 28.0.0 y hoy es AndroidX: lo tienes en versiones de la Support Library de Android.
El catálogo de versiones: libs.versions.toml
En vez de escribir "androidx.appcompat:appcompat:1.8.0" en cada módulo, apuntas las librerías y sus versiones una sola vez en gradle/libs.versions.toml. Es como la lista de piezas de la hoja de instrucciones: todos los módulos miran la misma, y si cambias la versión de una pieza, la cambias en un solo sitio. Los proyectos nuevos de Android Studio ya lo crean por defecto.
[versions]
agp = "9.5.0"
appcompat = "1.8.0"
[libraries]
androidx-appcompat = { group = "androidx.appcompat", name = "appcompat", version.ref = "appcompat" }
[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
Tiene tres secciones (y una cuarta opcional, [bundles], para agrupar librerías que siempre van juntas):
| Sección | Qué guarda |
|---|---|
[versions] |
Las versiones, con un nombre para reutilizarlas |
[libraries] |
Las librerías: grupo, nombre y qué versión usan |
[plugins] |
Los plugins de Gradle y su versión |
Desde los build.gradle.kts los usas con libs. delante, y cada guion se convierte en un punto: androidx-appcompat pasa a ser libs.androidx.appcompat, y el plugin android-application, libs.plugins.android.application. El Gradle de proyecto quedaría así:
plugins {
alias(libs.plugins.android.application) apply false
}
Comandos de Gradle desde el terminal
No hace falta instalar Gradle. Cada proyecto trae el Gradle Wrapper (gradlew), un pequeño script que descarga la versión exacta de Gradle que pide el proyecto y la ejecuta. Así todo el equipo, y el servidor de integración continua, construye con la misma versión. Esa versión está en gradle/wrapper/gradle-wrapper.properties:
distributionUrl=https\://services.gradle.org/distributions/gradle-9.9.0-bin.zip
Abre el terminal en la raíz del proyecto (en Android Studio, View > Tool Windows > Terminal) y usa estas tareas:
| Comando | Qué hace |
|---|---|
./gradlew assembleDebug |
Genera el APK de depuración en app/build/outputs/apk/ |
./gradlew installDebug |
Lo genera y lo instala en el emulador o en el móvil conectado |
./gradlew test |
Pasa los tests locales (los que no necesitan un dispositivo) |
./gradlew connectedAndroidTest |
Pasa los tests instrumentados en un emulador o móvil |
./gradlew :app:dependencies |
Muestra el árbol de librerías del módulo app, incluidas las que vienen de rebote |
./gradlew tasks |
Lista todas las tareas disponibles |
./gradlew clean |
Borra lo generado para construir desde cero |
El Debug de assembleDebug es el nombre de la variante. Si tienes otras, cambia esa parte: assembleRelease, testDebugUnitTest…
Pruébalo con un proyecto Kotlin
Para construir un proyecto Android hace falta el Android SDK, así que los comandos Android de este artículo están comprobados en la documentación oficial, no ejecutados. Lo que es de Gradle y no de Android sí se ha ejecutado: un proyecto Kotlin para JVM con la misma estructura (settings.gradle.kts, build.gradle.kts, gradle/libs.versions.toml y un módulo app).
El catálogo:
[versions]
kotlin = "2.4.10"
[libraries]
kotlin-test = { module = "org.jetbrains.kotlin:kotlin-test", version.ref = "kotlin" }
[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
El app/build.gradle.kts:
plugins {
alias(libs.plugins.kotlin.jvm)
application
}
kotlin {
jvmToolchain(21)
}
dependencies {
testImplementation(libs.kotlin.test)
}
application {
mainClass = "SaludoKt"
}
tasks.test {
useJUnitPlatform()
}
Un test sencillo para fun saludo(nombre: String) = "Hola, $nombre":
import kotlin.test.Test
import kotlin.test.assertEquals
class SaludoTest {
@Test
fun `saluda por el nombre`() {
assertEquals("Hola, Ana", saludo("Ana"))
}
}
Primero, el wrapper (este es el único paso que necesita Gradle instalado; después, siempre ./gradlew):
gradle wrapper --gradle-version 9.9.0
./gradlew --version
------------------------------------------------------------
Gradle 9.9.0
------------------------------------------------------------
Build time: 2026-11-06 15:49:35 UTC
Kotlin: 2.4.21
Launcher JVM: 21.0.13 (Eclipse Adoptium 21.0.13+9-LTS)
Después, los tests:
./gradlew clean test
> Task :app:clean
> Task :app:compileKotlin
> Task :app:jar
> Task :app:compileTestKotlin
> Task :app:test
BUILD SUCCESSFUL in 13s
5 actionable tasks: 5 executed
Si un test falla, Gradle para y te dice cuál. Que los tests se puedan lanzar con una sola orden, igual en tu equipo que en el servidor, es lo que permite trabajar con TDD sin fricción.
Y el árbol de dependencias del código de producción:
./gradlew :app:dependencies --configuration runtimeClasspath
runtimeClasspath - Runtime classpath of 'main'.
\--- org.jetbrains.kotlin:kotlin-stdlib:2.4.10
\--- org.jetbrains:annotations:13.0
kotlin-stdlib llega por el plugin de Kotlin, y annotations viene de rebote con ella: es una dependencia transitiva. En una app Android el árbol es mucho más largo, y esta tarea es la forma más rápida de averiguar de dónde sale una librería que no recuerdas haber añadido.
Sincronizar Gradle en Android Studio
Cada vez que cambias un fichero de Gradle, Android Studio necesita sincronizar: lee la nueva configuración, descarga lo que falte y comprueba que no hay errores. Pulsa Sync Now en el aviso que aparece arriba del editor o el botón Sync Project de la barra de menús.
En el lateral derecho tienes la ventana Gradle, con todas las tareas del proyecto agrupadas. Puedes lanzar cualquiera con doble clic, sin escribir comandos:
¿Qué es la carpeta .gradle?
Si buscas «.gradle» te encuentras tres cosas distintas con nombres parecidos:
- Ficheros que terminan en
.gradle, comobuild.gradle: son scripts de Gradle escritos en Groovy. Los de Kotlin terminan en.gradle.kts. - La carpeta
.gradleen la raíz del proyecto: una caché que genera Gradle para ir más rápido. No se sube al repositorio y, si la borras, Gradle la vuelve a crear; solo tardará más la siguiente vez. - La carpeta
.gradlede tu usuario (~/.gradleen Linux y macOS,C:\Users\<tú>\.gradleen Windows): guarda la caché de librerías descargadas, las versiones de Gradle que baja el wrapper y tu configuración global. Es compartida por todos tus proyectos.
Errores típicos
- Gradle no encuentra el Android SDK: revisa que
local.propertiestenga la ruta correcta ensdk.dir. Android Studio lo rellena al abrir el proyecto. - «The ‘org.jetbrains.kotlin.android’ plugin is no longer required for Kotlin support since AGP 9.0»: al actualizar a AGP 9, quita ese plugin de los dos
build.gradle.ktsy del catálogo. - Funciona en Android Studio pero no en el terminal (o al revés): comprueba que usas
./gradlewy no ungradleinstalado aparte con otra versión.
Siguiente paso
Si aún no tienes un proyecto, empieza por el Hola Mundo con Android Studio y Kotlin y abre sus Gradle Scripts con esta guía al lado. Después, prueba en el terminal ./gradlew tasks y ./gradlew :app:dependencies: en dos minutos sabrás qué puede hacer Gradle con tu proyecto y qué librerías arrastra.
Fuentes
Comprobado el 7 de noviembre de 2026 en la documentación oficial:
- Android Developers: Configure your build (ficheros de Gradle,
compileSdk,minSdk,targetSdky ejemplo de módulo), Android Gradle Plugin 9.5 release notes (AGP 9.5: Gradle 9.6.0 como mínimo, JDK 17, hasta API 37), Migrate to Kotlin DSL, Migrate to version catalogs, Add build dependencies, Migrate to built-in Kotlin, Build your app from the command line, Test from the command line y Migrate from Kotlin synthetics to view binding. - Gradle 9.9.0: Version catalogs, Gradle directories y Release notes.
Los comandos de Android (assembleDebug, installDebug, connectedAndroidTest) y el build.gradle.kts de Android solo se han comprobado en la documentación, no ejecutado. El proyecto Kotlin/JVM sí se ha ejecutado: Gradle 9.9.0 mediante el wrapper, lanzado desde la imagen oficial de Docker gradle:9.8.2-jdk21 (Eclipse Temurin 21.0.13), con el plugin de Kotlin 2.4.10, en Linux 7.0. Las capturas son del proyecto original de 2018.