On this page
An Android App Bundle (.aab) is Google Play's required publishing format. Instead of uploading device-specific APKs, you upload one app bundle and Google Play uses it to generate and serve the optimal, smaller APKs per device configuration (language, screen density, CPU architecture). This guide explains what a bundle is, why Play requires it, how it is signed, and how to build and upload one.
AAB vs APK
For a long time the standard Android install file was the APK — one file containing all assets for all devices. An Android App Bundle is a ZIP-like container (.aab) holding the app's compiled code and resources, but unlike an APK it is NOT installed on a device directly. Google Play uses the bundle to produce optimized split APKs per device.
| APK | AAB | |
|---|---|---|
| Upload target | Google Play and side-loading | Google Play only |
| Installed on device directly | Yes | No — Play serves split APKs generated from it |
| File size | One app, all configs (larger) | Smaller per device (only needed configs) |
| What you sign | You sign the APK | Google signs the final APKs via Play App Signing |
| Required by Play for new apps | APK uploads still accepted in limited cases | Yes — required format |
Who holds the signing keys
Signing a bundle ties into Play App Signing. There are two keys, and confusing them is the most common signing mistake.
| Key | Held by | Purpose |
|---|---|---|
| Upload key | You | Signs the bundle before upload so Google can verify your identity |
| App signing key | Google Play (or you) | Google signs the split APKs delivered to users |
How Google turns an AAB into the APKs users install
After you upload a bundle, Google Play runs Bundletool to produce device-specific split APKs: a base APK plus config splits (config.abi, config.xxxhdpi, config.en, etc.). The device then downloads only the splits it needs.
How to build and upload an AAB
Build in Android Studio
Build > Generate Signed Bundle / APK > Android App Bundle > select your upload keystore > Build. This produces app-release.aab.
Build on the command line
`./gradlew bundleRelease` produces the .aab in app/build/outputs/bundle/<variant>/. Configure signing via signingConfigs in build.gradle.
Upload to Play Console
In Test and release > Production (or the relevant testing track), create a new release, attach the .aab, review the pre-launch report, and roll out.
Validating your AAB locally before upload
Upload an app bundle that fails review — for example one missing a required architecture or signed with the wrong key — and you burn time in a new review cycle. Validating locally first is the cheapest protection against that. Google's Bundletool turns a bundle into the exact split APKs Play would serve, so you can install them on a device before you ever upload.
Install bundletool
Download the latest bundletool JAR from the Android developer docs (google.com/android/bundletool) or install it via SDK Manager's "bundletool" component. Put it on your PATH as bundletool.
Generate an APK set
Run `bundletool build-apks --bundle=app-release.aab --output=app.apks`. Add `--ks=upload.keystore --ks-key-alias=your-alias --ks-pass=pass:changeit --key-pass=pass:changeit` to test the signed output, mirroring how Play signs the result.
Inspect the split configuration
Run `bundletool dump manifest --apks=app.apks` to see the merged manifest, and `bundletool dump resources --apks=app.apks` to confirm assets and native libraries (.so files) are present for the ABIs you target. Missing splits here show up as install failures on those devices.
Install on a device
Run `bundletool install-apks --apks=app.apks` on a connected device. If the install succeeds and the app opens, your bundle is structurally valid and signed correctly — a failure here means fix before uploading.
Common AAB and upload problems
Frequently asked questions
Upload key error: upload key lost or reset
If your upload keystore is lost or compromised, request an upload key reset in Play Console (Setup > App integrity > Reset upload key). Google then issues a new upload key and signs your next bundle with the same app signing key, so existing users upgrade seamlessly. After the reset, you can no longer upload bundles signed with the old key — generate a new upload keystore and use it going forward.
App signing key upgrade prompts
Play may offer an app-signing-key upgrade (Setup > App integrity > App signing key upgrade) for apps already on Google Play. This lets you rotate the Google-held app signing key without losing user data or requiring a new app. The upgrade does not change your upload key — you keep signing bundles with your existing upload key. After the upgrade completes, re-register the new signing-key fingerprint with any API providers that authenticate by certificate (Google Maps, Firebase, OAuth).
Upload rejected: bundle signed with a different upload key
Play Console tracks the SHA-1/SHA-256 fingerprint of the key you first signed a bundle with. If a later upload is signed with a different key, Play rejects it as a signing-key mismatch. Either sign with the original upload key, or if that key is truly gone, request an upload-key reset and then sign with the new key.
Local install says app not installed
Almost always a signature conflict (a previously installed APK signed by a different key) or an attempt to sideload the .aab directly. Uninstall the existing app — or sign the local install with the same key as the existing build — then install split APKs generated by bundletool instead of the .aab.
Sources & references
Official Google documentation- Use Play App Signingsupport.google.com
- About Android app bundles (Android developers)developer.android.com
These links open Google's official Play Console Help pages used to verify this guide. AppsTestLab guidance is independent and not affiliated with Google.
Get help doing this