Introduction

You cannot install an .aab file directly on an Android device with adb install. An Android App Bundle is a publishing format, not an installable package. To test it on a device, you first use bundletool to generate device-specific APKs or a universal APK set, then install those APKs. Once that distinction is clear, the workflow is straightforward.

Why an .aab Is Not Directly Installable

An APK is the actual package Android installs. An App Bundle contains the ingredients Google Play or bundletool uses to build the right APK split set for a specific device configuration.

That is why this does not work:

adb install app-release.aab

The device installer expects APKs, not a bundle description.

Build an APK Set with bundletool

The usual local testing flow is:

1. build or obtain the signed .aab
2. use bundletool to generate an .apks archive
3. install the generated APK set onto the connected device

Example command:

1java -jar bundletool.jar build-apks \
2  --bundle=app-release.aab \
3  --output=app.apks \
4  --ks=my-release-key.jks \
5  --ks-key-alias=my-key-alias

If your keystore requires passwords, add --ks-pass and --key-pass as needed.

The resulting app.apks file is a container holding the APKs that match different ABIs, languages, and screen densities.

Install on a Connected Device

Once you have the APK set, connect a device with USB debugging enabled and confirm that adb sees it.

adb devices

Then install the correct split set for that device:

java -jar bundletool.jar install-apks \
  --apks=app.apks

bundletool talks to the device through adb, detects the device configuration, and installs only the required APKs.

That is the key reason to use install-apks instead of manually extracting random APK files from the archive.

Universal APK for Simpler Sideloading

If you need a single APK for quick local testing, generate a universal mode APK set.

1java -jar bundletool.jar build-apks \
2  --bundle=app-release.aab \
3  --output=app-universal.apks \
4  --mode=universal \
5  --ks=my-release-key.jks \
6  --ks-key-alias=my-key-alias

You can then extract the universal APK and install it with adb install, or still use install-apks on the .apks archive.

Universal APKs are convenient, but they are larger and less representative of what Google Play would deliver to a real device.

Typical Local Workflow

A practical debug cycle looks like this:

1./gradlew bundleRelease
2java -jar bundletool.jar build-apks \
3  --bundle=app/build/outputs/bundle/release/app-release.aab \
4  --output=app.apks \
5  --ks=my-release-key.jks \
6  --ks-key-alias=my-key-alias
7java -jar bundletool.jar install-apks --apks=app.apks

If you are testing debug builds, use the debug bundle and signing setup that matches your environment.

Troubleshoot Signing and Device Mismatch

If bundletool fails during installation, the two most common causes are signing problems and device-specific split mismatches. Make sure the bundle was built from the same app ID you expect on the device and that the signing key matches what Android allows for that package name. If an older build is already installed with a different signing certificate, uninstall it before retrying.

adb uninstall com.example.myapp

That simple cleanup step resolves many local sideload failures.

Common Pitfalls

• Trying to install the .aab directly with adb install.
• Building an APK set without signing information when the bundle is not already properly signed.
• Extracting APKs manually instead of letting bundletool install-apks choose the right splits.
• Forgetting to enable USB debugging or verify the device with adb devices.
• Using a universal APK for performance or size testing and assuming it matches Play delivery exactly.

Summary

• An Android App Bundle is not directly installable on a device.
• Use bundletool build-apks to convert the .aab into an APK set.
• Use bundletool install-apks to install the correct split APKs on a connected device.
• Generate a universal APK only when you specifically need a single installable artifact.
• For realistic local testing, follow the bundle-to-APK-set workflow instead of sideloading the .aab itself.