Test Android App Bundles with bundletool

After you build your Android App Bundle, you should test how Google Play uses it to generate APKs and how those APKs behave when deployed to a device. There are two ways you should consider testing your app bundle: locally using the bundletool command line tool and through Google Play by uploading your bundle to the Play Console and using a test track. This page explains how to use bundletool to test your app bundle locally.

bundletool is the underlying tool that Gradle, Android Studio, and Google Play use to build an Android App Bundle or convert an app bundle into the various APKs that are deployed to devices. bundletool is also available to you as a command line tool, so you can recreate, inspect, and verify Google Play’s server-side build of your app’s APKs.

You should use Android Studio and the Android plugin for Gradle to build and sign an Android App Bundle. However, if using the IDE is not an option (for example, because you’re using a continuous build server), you can also build your app bundle from the command line and sign it using jarsigner.

By default, the IDE does not use app bundles to deploy your app to a local device for testing. However, you can modify your run/debug configuration to use bundletool and deploy APKs from an app bundle in Android Studio and see how it affects your app's execution.

Download bundletool

If you haven't already done so, download bundletool from the GitHub repository.

Generate a set of APKs from your app bundle

When bundletool generates APKs from your app bundle, it includes them in a container called an APK set archive, which uses the .apks file extension. To generate an APK set for all device configurations your app supports from your app bundle, use the bundletool build-apks command, as shown below.

bundletool build-apks --bundle=/MyApp/my_app.aab --output=/MyApp/my_app.apks

Note that the command above creates an APK set of unsigned APKs. If you want to deploy the APKs to a device, you need to also include your app’s signing information, as shown in the command below.

bundletool build-apks --bundle=/MyApp/my_app.aab --output=/MyApp/my_app.apks
--ks=/MyApp/keystore.jks
--ks-pass=file:/MyApp/keystore.pwd
--ks-key-alias=MyKeyAlias
--key-pass=file:/MyApp/key.pwd

The table below describes the various flags and options you can set when using the bundletool build-apks command in greater detail. Only --bundle and --output are required—all other flags are optional.

Flag Description
--bundle=path (Required) Specifies the path to the app bundle you build using Android Studio. To learn more, read build an Android App Bundle.
--output=path (Required) Specifies the name of the output `.apks` file, which contains all the APK artifacts for your app. To test the artifacts in this file on a device, go to the section about how to deploy APKs to a connected device.
--aapt2=path Specifies a custom path to AAPT2. By default, bundletool includes its own version of AAPT2.
--ks=path Specifies the path to the deployment keystore used to sign the APKs. Although this flag is optional, if you don't include it, bundletool generates unsigned APKs. You must sign APKs to deploy them to a device. If you haven’t already done so, use Android Studio to generate a key and keystore.
--ks-pass=pass:password
or
--ks-pass=file:/path/to/file
Specifies your keystore’s password. If you’re specifying a password in plain text, qualify it with pass:. If you’re passing the path to a file that contains the password, qualify it with file:. If you specify a keystore using the --ks flag without specifying --ks-pass, bundletool prompts you for a password from the command line.
--ks-key-alias=alias Specifies the alias of the signing key you want to use.
--key-pass=pass:password
or
--key-pass=file:/path/to/file
Specifies the password for the signing key. If you’re specifying a password in plain text, qualify it with pass:. If you’re passing the path to a file that contains the password, qualify it with file:.

If this password is identical to the one for the keystore itself, you can omit this flag.

--connected-device Instructs bundletool to build APKs that target the configuration of a connected device. If you don’t include this flag, bundletool generates APKs for all device configurations your app supports.
--device-id=serial-number If you have more than one connected device, use this flag to specify the serial ID of the device to which you want to deploy your app.
--universal Include this flag if you want bundletool to also build an APK that includes your app’s dynamic features and is compatible with all devices.

Note: bundletool includes only dynamic feature modules that specify <dist:fusing dist:include="true"/> in the their manifest in a universal APK. To learn more, read about the Dynamic feature module manifest.

Keep in mind, these APKs are larger than those optimized for a particular device configuration. However, they’re easier to share with internal testers who, for example, want to test your app on multiple device configurations.

Deploy APKs to a connected device

After you generate a set of APKs, bundletool can deploy the right combination of APKs from that set to a connected device.

For example, if you have a connected device running Android 5.0 (API level 21) or higher, bundletool pushes the base APK, dynamic feature APKs, and configuration APKs required to run your app on that device. Alternatively, if your connected device is running Android 4.4 (API level 20) or lower, bundletool looks for a compatible multi-APK and deploys it to your device.

To deploy your app from an APK set, use the install-apks command and specify the path of the APK set using the --apks=/path/to/apks flag, as shown below. (If you have multiple devices connected, specify a target device by adding the --device-id=serial-id flag.)

bundletool install-apks --apks=/MyApp/my_app.apks

Generate a device-specific set of APKs

If you’d rather not build a set of APKs for all device configurations your app supports, you can build APKs that target only the configuration of a connected device using the --connected-device option, as shown below. (If you have multiple devices connected, specify a target device by including the --device-id=serial-id flag.)

bundletool build-apks --connected-device
--bundle=/MyApp/my_app.aab --output=/MyApp/my_app.apks

Extract APKs for a specific device configuration

If you have an existing APK set and you want to extract from it a subset of APKs that target a specific device configuration, you can use the extract-apks command. However you must first create a JSON file that describes the target device configuration.

To have bundletool generate a JSON file for a connected device, run the following command. (If you have multiple devices connected, specify a target device by adding the --device-id=serial-id flag.)

bundletool get-device-spec

bundletool creates a JSON file for your device in the directory the tool is located. You can then pass it to the bundletool extract-apks command, along with paths for the input and output APK sets, as follows:

bundletool extract-apks
--apks=/MyApp/my_existing_APK_set.apks
--output-dir=/MyApp/my_pixel2_APK_set.apks
--device-spec=/MyApp/bundletool/pixel2.json

Manually create a device specification JSON

If you don’t have access to the device for which you want to build a targeted APK set (for example, a friend wants to try your app with a device you don’t have on-hand), you can manually create a JSON file using the following format:

{
  "supportedAbis": ["arm64-v8a", "armeabi-v7a"],
  "supportedLocales": ["en", "fr"],
  "screenDensity": 640,
  "sdkVersion": 27
}

You can then pass this JSON to the bundle extract-apks command, as described in the previous section.