Nivel inicial14 min de lectura · Publicado el

Qué es Gradle en Android Studio y cómo se configura

Gradle en Android: build.gradle.kts es la hoja de instrucciones con sus piezas, como appcompat, y Gradle las monta y empaqueta en el APK. Gradle monta igual cada vezrubentejera.com build.gradle.ktsappcompatGradleigualcada vezAPK
build.gradle.kts es la hoja de instrucciones: qué piezas lleva (las dependencias, como appcompat) y de qué versión. Gradle monta y empaqueta el APK siguiéndola igual cada vez, y se salta los pasos que ya hizo si nada cambió.

¿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:

Panel de proyecto de Android Studio en vista Android: dentro de Gradle Scripts aparecen build.gradle del proyecto, build.gradle del módulo app, gradle-wrapper.properties, proguard-rules.pro, gradle.properties, settings.gradle y local.properties

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 plugins que declara qué plugins existen y en qué versión, con apply false para 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.
Los ficheros de Gradle y quién usa a quién: settings.gradle.kts dice qué módulos forman el proyecto con include(":app"); el build.gradle.kts de proyecto declara los plugins sin aplicarlos; el build.gradle.kts del módulo :app aplica los plugins, configura Android y añade las dependencias; y los dos build.gradle.kts leen con libs. el catálogo gradle/libs.versions.toml, con las librerías y los plugins y su versión en un solo sitio.
Las flechas continuas van hacia el módulo que se incluye o que aplica los plugins; las discontinuas, al catálogo de versiones que los dos 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 clase R, 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 el namespace, 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 cuyo minSdk es 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 un targetSdk mí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 28
  • minSdkVersion 19 y targetSdkVersion 28
  • minifyEnabled false
  • Comillas simples: 'proguard-rules.pro'
  • android.support.test.runner.AndroidJUnitRunner

Kotlin DSL (build.gradle.kts, hoy)

  • plugins { alias(libs.plugins.android.application) }
  • compileSdk = 36
  • minSdk = 23 y targetSdk = 36
  • isMinifyEnabled = 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:

Ventana Gradle en el lateral derecho de Android Studio: el proyecto HolaMundo y el módulo app con sus grupos de tareas android, build, help, install, other y verification, y el botón de sincronizar arriba a la izquierda

¿Qué es la carpeta .gradle?

Si buscas «.gradle» te encuentras tres cosas distintas con nombres parecidos:

  • Ficheros que terminan en .gradle, como build.gradle: son scripts de Gradle escritos en Groovy. Los de Kotlin terminan en .gradle.kts.
  • La carpeta .gradle en 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 .gradle de tu usuario (~/.gradle en Linux y macOS, C:\Users\<tú>\.gradle en 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.properties tenga la ruta correcta en sdk.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.kts y del catálogo.
  • Funciona en Android Studio pero no en el terminal (o al revés): comprueba que usas ./gradlew y no un gradle instalado 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:

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.