App Bundles

For most of Android's life, an APK was a universal artefact: one file contained every language, every density and every CPU architecture, and a device took what it needed. App Bundles invert that. You upload everything once, and the store builds a bespoke set of APKs for each device.

TL;DR#

An AAB (Android App Bundle) is an upload format. Devices do not install it.
Play (or bundletool) generates a split set per device: a base APK plus configuration splits for ABI, density and language.
Dynamic feature modules can be delivered at install time, soon after, or on demand.
Google Play has required AABs for new apps since 2021.
The signature is over the bundle from the developer's perspective, but devices verify the generated APKs — which is why Play App Signing exists.

Mental model#

Think of a made-to-measure clothing shop.

You bring the fabric and the patterns (the bundle). The shop does not hand you a bolt of cloth. It takes your measurements (the device's ABI, density, language) and cuts a garment that fits you (the split set). Everyone gets a different garment from the same pattern book.

Where the analogy breaks#

A tailor keeps the leftover cloth. Play does not ship the unused splits at all, but it does keep them available: if the user changes their language or plugs in a device with a different ABI, a different split may be needed later. The set is not immutable for the lifetime of the install.

The big picture#

Loading diagram…

Text description of this diagram

A five-stage pipeline. The app bundle contains base code and resources plus each dynamic feature module, keeping every density, ABI and language. The bundle manifest declares the modules and their delivery conditions. Play or bundletool selects the matching ABI, density and language resources and emits split APKs for one device. Delivery is install-time, fast-follow or on-demand. The package manager records the splits as one package sharing one UID, one data directory and one signature.

The key idea: nothing device-irrelevant is downloaded, but everything is still available if the device's configuration changes.

Deep dive#

What is in a bundle#

An AAB is a ZIP with a different contract from an APK:

BundleConfig.pb — bundle metadata and the compression/targeting configuration.
base/ — the base module: manifest, dex, resources.
One directory per dynamic feature module.
BUNDLE-METADATA/ — signing and other metadata.

The base module is mandatory. Dynamic features are optional units that can be delivered later.

Split types#

Play generates several kinds of split:

Split	Contents	Why
Base	core code and resources	always installed
ABI	`lib/<abi>/` for one ABI	avoids shipping four architectures
Density	drawables for one density	avoids shipping every density
Language	`values-<lang>/`	avoids shipping every translation
Dynamic feature	an optional module's code and resources	on-demand delivery

The device installs them as one package: one UID, one data directory, one signature, one entry in the launcher.

Delivery modes for dynamic features#

A dynamic feature module declares a delivery condition:

Install-time — included with the base install.
Fast-follow — downloaded automatically soon after install, without blocking first launch.
On-demand — downloaded when the app asks for it.

On-demand is the one that changes app architecture. The app must handle the module not being present: check whether it is installed, request it, show progress, and handle failure. The Play Core library provides the API; the app provides the UX.

Why Play required bundles#

From 2021, Google Play has required new apps to be published as App Bundles rather than APKs. The stated reason is size: a device downloads only what it needs, and the savings compound across languages, densities and ABIs.

The architectural consequence is larger than the size saving: the store now generates the installable artefact, which means the store is in the build path. That is why Play App Signing became the default — the developer uploads with an upload key, and Google re-signs the generated APKs with the app signing key.¹

bundletool, and testing without Play#

bundletool is the open-source tool that does what Play does: it takes an AAB and generates APKs. It can:

build a universal APK (all splits combined) for testing,
generate a device-specific set from a device spec,
install a set to a connected device.

That is how you test an AAB locally, and how CI verifies that a bundle produces a valid split set.

What bundles do not solve#

Bundles reduce download size, not app size on disk in every case. A few caveats:

All splits still count toward the install. The app's on-disk footprint is the sum of installed splits, and a user who changes language may accumulate more.
Dynamic features add complexity. The delivery API, the loading states and the fallbacks are real engineering work.
Not all stores use bundles. AAB is a Play format; other stores may still want a universal APK.

The last point matters for distribution strategy: an app that relies on on-demand modules is relying on Play's delivery machinery, not just on an Android platform feature.

Bundles and R8#

Bundles change the calculus for code shrinking. Because every split is generated per device, shipping unused code is less costly for a given user — but the total uploaded bundle still contains everything. R8 remains the right answer for reducing the base module, and it interacts with dynamic features: each feature module is shrunk independently, so a class used only by an on-demand feature should not be kept in the base.²

How it evolved#

Storage changes10 releases

API	Version	What changed
3	1.5 Cupcake	android.widget video and media improvements
12	3.1 Honeycomb	ParcelFileDescriptor improvements
15	4.0.3 Ice Cream Sandwich	New calendar and media provider APIs
19	4.4 KitKat	Storage Access Framework
24	7.0 Nougat	FileProvider and StrictMode for file URLs
29	10	Scoped storage with requestLegacyExternalStorage opt-out
30	11	Scoped storage enforced for targeting apps
33	13 Tiramisu	READ_MEDIA_IMAGES/VIDEO/AUDIO replace storage reads
34	14 Upside Down Cake	READ_MEDIA_VISUAL_USER_SELECTED
37	17 Cinnamon Bun	ACTION_PICK_CONTACTS gives session-scoped contact field access

2008–2018Universal APKOne file, every density, language and ABI.API 1

2018 →App BundleUpload a bundle; the store generates splits.API 28

2021 →Required by PlayNew apps must be published as bundles.API 30

2021 →Incremental installPlay can stream parts of an install while it runs.API 30

Under the hood#

PackageInstaller.javathe session API that installs split sets
SplitAssetLoader.javahow splits are loaded as one package
ApplicationInfo.javasplit names and the base/split relationship
the build-side packaging tools

Curiosity corner#

An AAB is a ZIP, but it is not installable. adb install app.aab fails; bundletool is how you turn it into something a device accepts.
The universal APK still exists as a test artefact. It is what bundletool produces when you ask for a build that runs on any device.
A split can be added after install. If the user adds a language, the language split can arrive later — the install is not frozen at first download.

Why does the build compile resources before dexing?Because resources and code are separate inputs: AAPT2 produces the compiled resource table and the R class, then the compiler uses…Open card →Why do Android icons have two layers?Adaptive icons separate a foreground and a background so launchers can mask them into different shapes without the developer drawi…Open card →Is an APK just a ZIP file?Almost. It is a ZIP archive with a specific layout: binary AndroidManifest.xml, classes.dex files, resources.arsc, res/, lib/<abi>…Open card →

Try it#

Turn a bundle into APKs

$ bundletool build-apks --bundle=app.aab --output=app.apks
bundletool build-apks --bundle=app.aab --output=app.apks --connected-device
bundletool install-apks --apks=app.apks
unzip -l app.apks | head -20

Example output

Base APK: base-master.apk
Split: base-arm64_v8a.apk
Split: base-xxhdpi.apk
Split: base-fr.apk
Split: feature-camera.apk

The --connected-device flag is the interesting one: it asks the attached device for its spec and generates only the splits that device would receive.