bundletool

Display help for a subcommand

$ bundletool help [subcommand]

$ bundletool build-apks --bundle [path/to/bundle.aab] --ks [path/to/key.keystore] --ks-key-alias [key_alias] --output [path/to/file.apks]

$ bundletool build-apks --bundle [path/to/bundle.aab] --ks [path/to/key.keystore] --ks-key-alias [key_alias] --ks-pass [pass:the_password] --output [path/to/file.apks]

$ bundletool build-apks --bundle [path/to/bundle.aab] --mode [universal] --ks [path/to/key.keystore] --ks-key-alias [key_alias] --output [path/to/file.apks]

$ bundletool install-apks --apks [path/to/file.apks]

$ bundletool get-size total --apks [path/to/file.apks]

$ bundletool get-device-spec --output [path/to/file.json]

$ bundletool validate --bundle [path/to/bundle.aab]

java -jar bundletool.jar <I>command</I> [options]

command
    The specific operation bundletool should perform. Examples include build-apks, get-size, validate, install-apks, and extract-apks. Each command has its own set of specific options.

build-apks
    Generates a set of device-specific APKs from an Android App Bundle (.aab file). This is the most frequently used command, essential for preparing apps for distribution. It supports various modes like universal APKs or signed APKs for publishing.

get-size
    Calculates and reports the estimated download and install sizes of an app bundle for different device configurations.

validate
    Performs various checks to ensure that an Android App Bundle is valid and correctly structured according to the App Bundle specification.

install-apks
    Installs a set of APKs (contained within an .apks archive generated by bundletool) onto a connected Android device.

extract-apks
    Extracts a device-specific subset of APKs from an .apks archive, useful for debugging or sharing specific APKs.

dump-debug-info
    Provides detailed debug information about the contents and structure of an Android App Bundle, useful for debugging and analysis.

bundletool is the underlying command-line utility that powers Android Studio, the Android Gradle plugin, and Google Play when building and packaging Android apps. It's primarily used for two main purposes: generating optimized APKs from an Android App Bundle (.aab file) and inspecting the contents of an App Bundle or generated APKs.

Android App Bundles are the standard publishing format for Android apps, offering benefits like smaller download sizes and features on demand. bundletool ensures that your app is optimized for various device configurations by generating a set of split APKs (base, configuration, and feature APKs) specific to a device's architecture, language, and screen density. It can also generate a single universal APK for testing purposes. Beyond APK generation, it offers utilities to extract device-specific APKs, install them, validate bundles, and measure their sizes. It's an essential tool for developers managing app distribution on Google Play and for local testing of App Bundles.

• Java Dependency: bundletool is a Java .jar file and requires a Java Runtime Environment (JRE) 8 or higher to be installed and configured on the system.
• Output Format: The build-apks command outputs an .apks file, which is a ZIP archive containing multiple APKs, not a single installable APK. It must be processed by bundletool install-apks or uploaded to Google Play for distribution.
• Signing Requirements: For production use, generated APKs must be properly signed with your app's release key. bundletool provides options for signing during the build-apks process.
• No Direct Linux Executable: Unlike many Linux commands, bundletool is not a native binary but rather a Java archive executed via the Java Virtual Machine.

The build-apks command, being central to bundletool's functionality, supports several important options to control APK generation:

• --bundle=file: (Required) Path to the input Android App Bundle (.aab) file.
  
• --output=file: (Required) Path where the generated .apks archive will be saved.
  
• --mode=mode: Specifies the APK generation mode. Common values include universal (generates a single APK compatible with all devices) and system (for pre-installed apps). Defaults to generating a set of split APKs.
  
• --ks=file: Path to the Java KeyStore (.jks) file containing the signing key.
  
• --ks-pass=pass: Password for the keystore.
  
• --ks-key-alias=alias: Alias of the key within the keystore to use for signing.
  
• --key-pass=pass: Password for the specific key alias.
  
• --local-testing: Generates unsigned APKs without enabling module fusion, ideal for quick local testing and debugging.
  
• --device-spec=file: Path to a JSON file describing a target device, allowing bundletool to generate a specific set of APKs tailored for that device.
  

When bundletool builds APKs, it outputs a single .apks file. This is fundamentally a ZIP archive containing all the generated split APKs, the base APK, and other metadata necessary for dynamic delivery. It is crucial to understand that this .apks file is not directly installable on an Android device. Instead, tools like bundletool install-apks, Google Play, or the Play Console are designed to parse this archive and deploy the correct set of APKs (or a single universal APK) to a target device based on its configuration. For local testing, you typically use bundletool install-apks --apks=<file>.

bundletool was introduced by Google alongside the Android App Bundle format itself, which was initially announced at Google I/O in 2018. Its primary purpose was to provide the underlying technology for Google Play's Dynamic Delivery system, enabling developers to leverage the benefits of App Bundles by generating optimized APKs for different device configurations. It began as an internal tool used by Android Studio and the Android Gradle plugin, and was later open-sourced and made available as a standalone command-line utility for developers to directly interact with App Bundles. Its continuous development is closely tied to the evolution of Android's app distribution model and optimization efforts.

adb(1): Android Debug Bridge, for installing and managing applications on Android devices., apksigner(1): Android SDK tool for signing APKs, an alternative or complementary tool for signing operations., zipalign(1): Android SDK tool for optimizing APK files, implicitly handled by bundletool during APK generation.