Skip to content

Most visited

Recently visited

navigation

Build Your App from the Command Line

You can execute all the build tasks available to your Android project using the Gradle wrapper command line tool. It's available as a batch file for Windows (gradlew.bat) and a shell script for Linux and Mac (gradlew.sh), and it's accessible from the root of each project you create with Android Studio.

To run a task with the wrapper, use one of the following commands:

To see a list of all available build tasks for your project, execute tasks:

gradlew tasks

The rest of this page describes the basics to build and run your app with the Gradle wrapper. For more information about how to set up your Android build, see Configure Your Build.

If you'd prefer to use the Android Studio tools instead of the command line tools, instead see Build and Run Your App.

About build types

By default, there are two build types available for every Android app: one for debugging your app—the debug build—and one for releasing your app to users—the release build. The resulting APK from each build must be signed with a certificate before you can install on an emulator or device. The debug build is automatically signed with a debug key provided by the SDK tools (it's insecure and you cannot publish this APK to Google Play Store), and the release build must be signed with your own private key.

If you want to build an APK for release, it's important that you first read Sign Your App. That page describes the procedure for generating a private key and then using it to sign your APK file. If you're just getting started, however, you can quickly run your apps on an emulator or a connected device by building a debug APK.

You can also define a custom build type in your build.gradle file and configure it to be signed as a debug build by including debuggable true. For more information, see Configure Build Variants.

Build a debug APK

For immediate app testing and debugging, you can build a debug APK. The debug APK is signed with a debug key provided by the SDK tools and allows debugging through adb.

To build a debug APK, open a command line and navigate to the root of your project directory—from Android Studio, select View > Tool Windows > Terminal. To initiate a debug build, invoke the assembleDebug task:

gradlew assembleDebug

This creates an APK named module_name-debug.apk in project_name/module_name/build/outputs/apk/. The file is already signed with the debug key and aligned with zipalign, so you can immediately install it on a device.

Or to build the APK and immediately install it on a running emulator or connected device, instead invoke installDebug:

gradlew installDebug

The "Debug" part in the above task names is just a camel-case version of the build variant name, so it can be replaced with whichever build variant you want to assemble or install. For example, if you have a "demo" product flavor, then you can build the debug version with the assembleDemoDebug task.

To see all the build and install tasks available for each variant (including uninstall tasks), run the tasks task.

Also see the section about how to run your app on the emulator and run your app on a device.

Build a release APK

When you're ready to release and distribute your app, you must build a release APK so it is signed with your private key.

There are two approaches to building a release APK: build an unsigned package and then manually align and sign the package, or allow the build script to do that for you.

Build an unsigned APK

To build an unsigned APK, open a command line and navigate to the root of your project directory—from Android Studio, select View > Tool Windows > Terminal. Then invoke the assembleRelease task:

gradlew assembleRelease

This creates an APK named module_name-unsigned.apk in project_name/module_name/build/outputs/apk/. The APK is unsigned and unaligned at this point—it can't be installed until signed with your private key.

Now you must align the APK with zipalign and sign it with apksigner. To complete this procedure, see the instructions to sign your app manually.

Build an aligned and signed APK

Instead of running an assemble build and then manually aligning and signing your package, as described above, you can instruct Gradle to align and sign it for you. To do so, you must provide the path to your keystore, the name of your key alias, and the password for each in your module's build.gradle file.

  1. First, you need a keystore. If you don't have one, see the first step in the guide to sign your app manually.
  2. Open the module-level build.gradle file and add entries for storeFile, storePassword, keyAlias and keyPassword. For example:
    android {
        ...
        defaultConfig { ... }
        signingConfigs {
            release {
                storeFile file("my-release-key.jks")
                storePassword "password"
                keyAlias "my-alias"
                keyPassword "password"
            }
        }
        buildTypes {
            release {
                ...
                signingConfig signingConfigs.release
            }
        }
    }
    

    Because Gradle reads paths relative to the build.gradle, the above example works only if my-release-key.jks is in the same directory as the build.gradle file.

    Note: In this case, the keystore and key password are visible directly in the build.gradle file. For improved security, you should remove these details from the build file. Read about how to secure your private key.

  3. Open a command line in your project root directory and invoke the assembleRelease task:
    gradlew assembleRelease
    

This creates an APK named module_name-release.apk in project_name/module_name/build/outputs/apk/. This APK file is signed with the private key specified in your build.gradle file and aligned with zipalign.

And now that you've configured the release build with your signing key, the "install" task is available for that build type. So you can build, align, sign, and install the release APK on an emulator or device all with the installRelease task.

An APK signed with your private key is ready for distribution, but you should first read more about how to publish your app and review the Google Play launch checklist.

Run your app on the emulator

To use the Android Emulator, you must create an Android Virtual Device (AVD) using Android Studio.

Once you have an AVD, start the Android Emulator and install your app as follows:

  1. In a command line, navigate to android_sdk/tools/ and start the emulator by specifying your AVD:

    emulator -avd avd_name

    If you're unsure of the AVD name, execute emulator -list-avds.

  2. Now you can install your app using either the Gradle install tasks mentioned above or the adb tool:
    adb install path/to/your_app.apk
    

    All built APKs are saved in project_name/module_name/build/outputs/apk/.

For more information, see Run Apps on the Android Emulator.

Run your app on a device

Before you can run your app on a device, you must enable USB debugging on your device. You can find the option under Settings > Developer options.

Note: On Android 4.2 and newer, Developer options is hidden by default. To make it available, go to Settings > About phone and tap Build number seven times. Return to the previous screen to find Developer options.

Once your device is set up and connected via USB, you can install your app using either the Gradle install tasks mentioned above or the adb tool:

adb -d install path/to/your_app.apk

All built APKs are saved in project_name/module_name/build/outputs/apk/.

For more information, see Run Apps on a Hardware Device.

This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a one-minute survey?
Help us improve Android tools and documentation.