Configure your build

The Android build system compiles app resources and source code and packages them into APKs or Android App Bundles that you can test, deploy, sign, and distribute.

Android build glossary

Gradle and the Android Gradle plugin help you configure the following aspects of your build:

Java versions in Android builds

Whether your source code is written in Java, Kotlin, or both, there are several places you must choose a JDK or Java language version for your build. See Java versions in Android builds for details.

Build configuration files

Creating custom build configurations requires you to make changes to one or more build configuration files. These plain-text files use a domain-specific language (DSL) to describe and manipulate the build logic using Kotlin script, which is a flavor of the Kotlin language. You can also use Groovy, which is a dynamic language for the Java Virtual Machine (JVM), to configure your builds.

You don't need to know Kotlin script or Groovy to start configuring your build because the Android Gradle plugin introduces most of the DSL elements you need. To learn more about the Android Gradle plugin DSL, read the DSL reference documentation. Kotlin script also relies on the underlying Gradle Kotlin DSL

When starting a new project, Android Studio automatically creates some of these files for you and populates them based on sensible defaults. For an overview of the created files, see Android build structure.

The Gradle Wrapper file

The Gradle wrapper (gradlew) is a small application included with your source code that downloads and launches Gradle itself. This creates more-consistent build execution. Developers download the application source and run gradlew. This downloads the required Gradle distribution, and launches Gradle to build your application.

The gradle/wrapper/gradle-wrapper.properties file contains a property, distributionUrl, that describes which version of Gradle is used to run your build.

The Gradle settings file

The settings.gradle.kts file (for the Kotlin DSL) or settings.gradle file (for the Groovy DSL) is located in the root project directory. This settings file defines project-level repository settings and informs Gradle which modules it should include when building your app. Multi-module projects need to specify each module that should go into the final build.

Kotlin

pluginManagement {

    /**
      * The pluginManagement.repositories block configures the
      * repositories Gradle uses to search or download the Gradle plugins and
      * their transitive dependencies. Gradle pre-configures support for remote
      * repositories such as JCenter, Maven Central, and Ivy. You can also use
      * local repositories or define your own remote repositories. Here we
      * define the Gradle Plugin Portal, Google's Maven repository,
      * and the Maven Central Repository as the repositories Gradle should use to look for its
      * dependencies.
      */

    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {

    /**
      * The dependencyResolutionManagement.repositories
      * block is where you configure the repositories and dependencies used by
      * all modules in your project, such as libraries that you are using to
      * create your application. However, you should configure module-specific
      * dependencies in each module-level build.gradle file. For new projects,
      * Android Studio includes Google's Maven repository and the Maven Central
      * Repository by default, but it does not configure any dependencies (unless
      * you select a template that requires some).
      */

  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
      google()
      mavenCentral()
  }
}
rootProject.name = "My Application"
include(":app")

Groovy

pluginManagement {

    /**
      * The pluginManagement.repositories block configures the
      * repositories Gradle uses to search or download the Gradle plugins and
      * their transitive dependencies. Gradle pre-configures support for remote
      * repositories such as JCenter, Maven Central, and Ivy. You can also use
      * local repositories or define your own remote repositories. Here we
      * define the Gradle Plugin Portal, Google's Maven repository,
      * and the Maven Central Repository as the repositories Gradle should use to look for its
      * dependencies.
      */

    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {

    /**
      * The dependencyResolutionManagement.repositories
      * block is where you configure the repositories and dependencies used by
      * all modules in your project, such as libraries that you are using to
      * create your application. However, you should configure module-specific
      * dependencies in each module-level build.gradle file. For new projects,
      * Android Studio includes Google's Maven repository and the Maven Central
      * Repository by default, but it does not configure any dependencies (unless
      * you select a template that requires some).
      */

    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
rootProject.name = "My Application"
include ':app'

The top-level build file

The top-level build.gradle.kts file (for the Kotlin DSL) or build.gradle file (for the Groovy DSL) is located in the root project directory. It typically defines the common versions of plugins used by modules in your project.

The following code sample describes the default settings and DSL elements in the top-level build script after creating a new project:

The module-level build file

The module-level build.gradle.kts (for the Kotlin DSL) or build.gradle file (for the Groovy DSL) is located in each project/module/ directory. It lets you configure build settings for the specific module it is located in. Configuring these build settings lets you provide custom packaging options, such as additional build types and product flavors, and override settings in the main/ app manifest or top-level build script.

Android SDK Settings

The module-level build file for your application includes settings that indicate Android SDK versions used when compiling, selecting platform behaviors, and specifying the minimum version that your application runs on.

Sample app-module build script

This sample Android app module build script outlines some of the basic DSL elements and settings:

Kotlin

/**
 * The first section in the build configuration applies the Android Gradle plugin
 * to this build and makes the android block available to specify
 * Android-specific build options.
 */

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

/**
 * Locate (and possibly download) a JDK used to build your kotlin
 * source code. This also acts as a default for sourceCompatibility,
 * targetCompatibility and jvmTarget. Note that this does not affect which JDK
 * is used to run the Gradle build itself, and does not need to take into
 * account the JDK version required by Gradle plugins (such as the
 * Android Gradle Plugin)
 */
kotlin {
    jvmToolchain(11)
}

/**
 * The android block is where you configure all your Android-specific
 * build options.
 */

android {

    /**
     * The app's namespace. Used primarily to access app resources.
     */

    namespace = "com.example.myapp"

    /**
     * compileSdk specifies the Android API level Gradle should use to
     * compile your app. This means your app can use the API features included in
     * this API level and lower.
     */

    compileSdk = 36

    /**
     * The defaultConfig block encapsulates default settings and entries for all
     * build variants and can override some attributes in main/AndroidManifest.xml
     * dynamically from the build system. You can configure product flavors to override
     * these values for different versions of your app.
     */

    defaultConfig {

        // Uniquely identifies the package for publishing.
        applicationId = "com.example.myapp"

        // Defines the minimum API level required to run the app.
        minSdk = 23

        // Specifies the API level used to test the app.
        targetSdk = 36

        // Defines the version number of your app.
        versionCode = 1

        // Defines a user-friendly version name for your app.
        versionName = "1.0"
    }

    /**
     * The buildTypes block is where you can configure multiple build types.
     * By default, the build system defines two build types: debug and release. The
     * debug build type is not explicitly shown in the default build configuration,
     * but it includes debugging tools and is signed with the debug key. The release
     * build type applies ProGuard settings and is not signed by default.
     */

    buildTypes {

        /**
         * By default, Android Studio configures the release build type to enable code
         * shrinking, using minifyEnabled, and specifies the default ProGuard rules file.
         */

        getByName("release") {
            isMinifyEnabled = true // Enables code shrinking for the release build type.
            proguardFiles(
                getDefaultProguardFile("proguard-android.txt"),
                "proguard-rules.pro"
            )
        }
    }

    /**
     * The productFlavors block is where you can configure multiple product flavors.
     * This lets you create different versions of your app that can
     * override the defaultConfig block with their own settings. Product flavors
     * are optional, and the build system does not create them by default.
     *
     * This example creates a free and paid product flavor. Each product flavor
     * then specifies its own application ID, so that they can exist on the Google
     * Play Store or an Android device simultaneously.
     *
     * If you declare product flavors, you must also declare flavor dimensions
     * and assign each flavor to a flavor dimension.
     */

    flavorDimensions += "tier"
    productFlavors {
        create("free") {
            dimension = "tier"
            applicationId = "com.example.myapp.free"
        }

        create("paid") {
            dimension = "tier"
            applicationId = "com.example.myapp.paid"
        }
    }

    /**
     * To override source and target compatibility (if different from the
     * toolchain JDK version), add the following. All of these
     * default to the same value as kotlin.jvmToolchain. If you're using the
     * same version for these values and kotlin.jvmToolchain, you can
     * remove these blocks.
     */
    //compileOptions {
    //    sourceCompatibility = JavaVersion.VERSION_11
    //    targetCompatibility = JavaVersion.VERSION_11
    //}
    //kotlinOptions {
    //    jvmTarget = "11"
    //}
}

/**
 * The dependencies block in the module-level build configuration file
 * specifies dependencies required to build only the module itself.
 * To learn more, go to Add build dependencies.
 */

dependencies {
    implementation(project(":lib"))
    implementation("androidx.appcompat:appcompat:1.7.1")
    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar"))))
}

Groovy

/**
 * The first line in the build configuration applies the Android Gradle plugin
 * to this build and makes the android block available to specify
 * Android-specific build options.
 */

plugins {
    id 'com.android.application'
}

/**
 * Locate (and possibly download) a JDK used to build your kotlin
 * source code. This also acts as a default for sourceCompatibility,
 * targetCompatibility and jvmTarget. Note that this does not affect which JDK
 * is used to run the Gradle build itself, and does not need to take into
 * account the JDK version required by Gradle plugins (such as the
 * Android Gradle Plugin)
 */
kotlin {
    jvmToolchain 11
}

/**
 * The android block is where you configure all your Android-specific
 * build options.
 */

android {

    /**
     * The app's namespace. Used primarily to access app resources.
     */

    namespace 'com.example.myapp'

    /**
     * compileSdk specifies the Android API level Gradle should use to
     * compile your app. This means your app can use the API features included in
     * this API level and lower.
     */

    compileSdk 36

    /**
     * The defaultConfig block encapsulates default settings and entries for all
     * build variants and can override some attributes in main/AndroidManifest.xml
     * dynamically from the build system. You can configure product flavors to override
     * these values for different versions of your app.
     */

    defaultConfig {

        // Uniquely identifies the package for publishing.
        applicationId 'com.example.myapp'

        // Defines the minimum API level required to run the app.
        minSdk 23

        // Specifies the API level used to test the app.
        targetSdk 36

        // Defines the version number of your app.
        versionCode 1

        // Defines a user-friendly version name for your app.
        versionName "1.0"
    }

    /**
     * The buildTypes block is where you can configure multiple build types.
     * By default, the build system defines two build types: debug and release. The
     * debug build type is not explicitly shown in the default build configuration,
     * but it includes debugging tools and is signed with the debug key. The release
     * build type applies ProGuard settings and is not signed by default.
     */

    buildTypes {

        /**
         * By default, Android Studio configures the release build type to enable code
         * shrinking, using minifyEnabled, and specifies the default ProGuard rules file.
         */

        release {
              minifyEnabled true // Enables code shrinking for the release build type.
              proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }

    /**
     * The productFlavors block is where you can configure multiple product flavors.
     * This lets you create different versions of your app that can
     * override the defaultConfig block with their own settings. Product flavors
     * are optional, and the build system does not create them by default.
     *
     * This example creates a free and paid product flavor. Each product flavor
     * then specifies its own application ID, so that they can exist on the Google
     * Play Store or an Android device simultaneously.
     *
     * If you declare product flavors, you must also declare flavor dimensions
     * and assign each flavor to a flavor dimension.
     */

    flavorDimensions "tier"
    productFlavors {
        free {
            dimension "tier"
            applicationId 'com.example.myapp.free'
        }

        paid {
            dimension "tier"
            applicationId 'com.example.myapp.paid'
        }
    }

    /**
     * To override source and target compatibility (if different from the
     * tool chain JDK version), add the following. All of these
     * default to the same value as kotlin.jvmToolchain. If you're using the
     * same version for these values and kotlin.jvmToolchain, you can
     * remove these blocks.
     */
    //compileOptions {
    //    sourceCompatibility JavaVersion.VERSION_11
    //    targetCompatibility JavaVersion.VERSION_11
    //}
    //kotlinOptions {
    //    jvmTarget = '11'
    //}
}

/**
 * The dependencies block in the module-level build configuration file
 * specifies dependencies required to build only the module itself.
 * To learn more, go to Add build dependencies.
 */

dependencies {
    implementation project(":lib")
    implementation 'androidx.appcompat:appcompat:1.7.1'
    implementation fileTree(dir: 'libs', include: ['*.jar'])
}

Gradle properties files

Gradle also includes two properties files, located in your root project directory, that you can use to specify settings for the Gradle build toolkit itself:

Remap the NDK to a shorter path (Windows only)

In Windows, tools in the installed NDK folder, such as ld.exe, end up with long paths. The tools don't support long paths well.

To create a shorter path, in local.properties, set the property ndk.symlinkdir to request that the Android Gradle plugin create a symlink to the NDK. The path of that symlink can be shorter than the existing NDK folder. For example, ndk.symlinkdir = C:\ results in the following symlink: C:\ndk\19.0.5232133

Sync project with Gradle files

When you make changes to the build configuration files in your project, Android Studio requires that you sync your project files so that it can import your build configuration changes and run some checks to make sure your configuration doesn't create build errors.

To sync your project files, click Sync Now in the notification bar that appears when you make a change, as shown in figure 2, or click Sync Project

from the menu bar. If Android Studio finds any errors with your configuration — for example, your source code uses API features that are only available in an API level higher than your compileSdkVersion — the Messages window describes the issue.

Source sets

Android Studio logically groups source code and resources for each module into source sets. When you create a new module, Android Studio creates a main/ source set within the module. A module's main/ source set includes the code and resources used by all its build variants.

Additional source set directories are optional, and Android Studio doesn't automatically create them for you when you configure new build variants. However, creating source sets, similar to main/, helps organize files and resources that Gradle should only use when building certain versions of your app:

For example, to generate the "fullDebug" version of your app, the build system merges code, settings, and resources from following source sets:

Note: When you create a new file or directory in Android Studio, use the File > New menu options to create it for a specific source set. The source sets you can choose from are based on your build configurations, and Android Studio automatically creates the required directories if they don't already exist.

If different source sets contain different versions of the same file, Gradle uses the following priority order when deciding which file to use. Source sets on the left override the files and settings of source sets to the right:

This allows Gradle to use files that are specific to the build variant you are trying to build while reusing activities, application logic, and resources that are common to other versions of your app.

When merging multiple manifests, Gradle uses the same priority order so each build variant can define different components or permissions in the final manifest. To learn more about creating custom source sets, read Create source sets.

Version catalogs

If your build contains multiple modules with common dependencies, or you have multiple independent projects with common dependencies, we recommend that you use a version catalog or bill of materials (BOM) to specify the common versions.

Other build systems

Building Android apps with Bazel is possible but not officially supported. Android Studio does not officially support Bazel projects.

To better understand the current limitations of building with Bazel, see the known issues.

Configure your build Stay organized with collections Save and categorize content based on your preferences.

Android build glossary

Java versions in Android builds

Build configuration files

The Gradle Wrapper file

The Gradle settings file

Kotlin

Groovy

The top-level build file

Kotlin

Groovy

The module-level build file

Android SDK Settings

Kotlin

Groovy

Sample app-module build script

Kotlin

Groovy

Gradle properties files

Remap the NDK to a shorter path (Windows only)

Sync project with Gradle files

Source sets

Version catalogs

Other build systems