Gradle Tutorial for Android: Getting Started

In this Gradle Build Script tutorial you’ll learn the basic syntax in build.gradle files generated by Android Studio. You’ll also learn about gradlew tasks, build types, product flavors, build variants, and how to add additional information such as the date to the APK file name. By Irina Galata.

4.8 (16) · 1 Review

Save for later

In this tutorial, you’ll gain a better understanding of what Gradle is, and how you can use Gradle to supercharge your builds. By the end of this tutorial you should be able to

  1. Build your Android apps from the command-line
  2. Read through a Gradle build file
  3. Create your own Gradle plugin
  4. Create build flavors for profit!
Note: This tutorial assumes you’re already familiar with the basics of Android development. If you are completely new to Android development, read through our Beginning Android Development tutorials to familiarize yourself with the basics.

What is Gradle?

Gradle is an open source build automation system. It brings the convenience of a Groovy-based DSL along with the advantages of Ant and Maven. With Gradle, you can easily manipulate the build process and its logic to create multiple versions of your app. It’s much easier to use and a lot more concise and flexible when compared to Ant or Maven alone.

So, there was little wonder why during Google I/O in May 2013, the Android Gradle plugin was introduced as the build tool built into the first preview of Android Studio :]

Getting Started

Download SocializifyStarter, the starter project for this tutorial. At minimum, you’ll need Android Studio 3.0 installed on your computer. Open the project in Android Studio, and you’ll be prompted to setup the Gradle wrapper:

Setup Gradle wrapper

Choose OK to configure the wrapper, which you’ll learn more about later in the tutorial.

Depending on which version of Android Studio you’re running, you may also be prompted to update the Gradle plugin:

Update gradle plugin

Choose Update to finish opening the project in Android Studio.

Before starting working with the project, let’s review its structure in the Project pane in Android Studio:

Project structure

Pay attention to the files with the green Gradle icon and .gradle extension. These files are generated by Android Studio automatically during project creation. They are responsible for the processing of your project’s build. They contain the necessary info about the project structure, library dependencies, library versions, and the app versions you’ll get as a result of the build process.

Project-level build.gradle

Find the build.gradle file in the root directory of the project. It’s called a top-level (project-level) build.gradle file. It contains the settings which are applied to all modules of the project.

Note: If you’re unfamiliar with modules, checkout out our second tutorial on Android studio found here.
// 1
buildscript {
    // 2
    repositories {
    // 3
    dependencies {
        classpath ''
        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:1.1.51'

// 4
allprojects {
    repositories {

Here’s what’s going on, step by step:

  1. In the buildscript block you define settings needed to perform your project building.
  2. In the repositories block you add names of the repositories that Gradle should search for the libraries you use.
  3. The dependencies block contains necessary plugin dependencies, in this case the Gradle and Kotlin plugins. Do not put your module dependencies in this block.
  4. The structure of the allprojects block is similar to the buildscript block, but here you define repositories for all of your modules, not for Gradle itself. Usually you don’t define the dependencies section for allprojects. The dependencies for each module are different and should reside in the module-level build.gradle.

Module-level build.gradle

Now go to the build.gradle file in the app module directory. It contains dependencies (libraries which a module relies on), and instructions for the build process. Each module defines its own build.gradle file.

// 1
apply plugin: ''
apply plugin: 'kotlin-android'
apply plugin: 'kotlin-android-extensions'

// 2
android {
    // 3
    compileSdkVersion 27
    // 4
    buildToolsVersion "26.0.2"
    // 5
    defaultConfig {
        // 6
        applicationId "com.raywenderlich.socializify"
        // 7
        minSdkVersion 21
        // 8
        targetSdkVersion 27
        // 9
        versionCode 1
        // 10
        versionName "1.0"

// 11
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation 'org.jetbrains.kotlin:kotlin-stdlib-jre7:1.1.51'
    implementation ''
    implementation ''

The code above does the following:

  1. Specifies a list of plugins needed to build the module. The plugin is necessary in order to setup the Android-specific settings of the build process. Here you can also use if you’re creating a library module. The kotlin-android and kotlin-android-extensions plugins allow you to use the Kotlin language and the Kotlin Android extensions in your module.
  2. In the android block you place all platform-specific options of the module.
  3. The compileSdkVersion option indicates the API level your app will be compiled with. In other words, you cannot use features from an API higher than this value. Here, you’ve set the value to use APIs from Android Oreo.
  4. The buildToolsVersion option indicates the version of the compiler. From Gradle plugin 3.0.0 onward, this field is optional. If it is not specified, the Android SDK uses the most recent downloaded version of the Build Tools.
  5. The defaultConfig block contains options which will be applied to all build versions (e.g., debug, release, etc) of your app by default.
  6. The applicationId is the identifier of your app. It should be unique so as to successfully publish or update your app on Google Play Store.
  7. In order to set the lowest API level supported, use minSdkVersion. Your app will not be available in the Play Store for the devices running on lower API levels.
  8. Note: To get more acquainted with the Android SDK versions read our tutorial covering that topic
  9. The targetSdkVersion parameter defines the maximum API level your app has beeen tested on. That is to say, you’re sure your app works properly on the devices with this SDK version, and it doesn’t require any backward compatibility behaviors. The best approach is to thoroughly test an app using the latest API, keeping your targetSdkVersion value equal to compileSdkVersion.
  10. versionCode is a numeric value for the app version.
  11. versionName is a user-friendly string for the app version.
  12. The dependencies block contains all dependencies needed for this module. Later in this tutorial, you’ll find out more about managing your project’s dependencies.
Note: To get more acquainted with the Android SDK versions read our tutorial covering that topic


Meng Taing

Tech Editor

Vijay Sharma

Final Pass Editor

Joe Howard

Team Lead

Over 300 content creators. Join our team.