If you're interested in trying an Android Generic System Image (GSI) on your device for compatibility testing, read on for step by step instructions.
Note: make sure to read the introduction and device requirements before starting the codelab.
Android Generic System Images (GSIs) rely on Project Treble, which provides a consistent, testable interface between Android OS and a vendor's implementation. A vendor's implementation is also called a Board Support Package (BSP). As illustrated in the follow graph, the Treble interface allows a BSP to communicate with Android OSes in a standard way, hence makes it possible to update Android OS without updating BSP:
Because GSIs are Android OS builds that conform with the Treble interface, they can run on any Android device that is fully Treble-compliant.This flexibility gives you additional ways to test and debug app compatibility issues on different versions of Android using a smaller set of hardware devices.
A Generic System Image (GSI) is a pure Android implementation with unmodified Android Open Source Project (AOSP) code; In other words, a GSI for a certain Android version contains all the common core code found on all devices running that version of Android, for example, Android 11, excluding any vendor customization or extensions from silicon manufacturers, device manufacturers, or carriers.
When you test your app using a GSI, you would find out how your app performs on a baseline Android system that supports CDD-tested, standard behaviors that are shared by all other Treble-compliant devices.
Because a GSI can run on a variety of Treble-compliant devices, you have greater flexibility when deciding what devices to use for your test and development environment. For example, if you don't have a Pixel device but want to test your app with Android 11 on a hardware device, you can install an Android 11 GSI on another Treble-compliant device, even if that device is never updated by the manufacturer to Android 11.
GSIs can also help you get a head start on your compatibility testing during the Developer Preview and Beta phases.
To use an Android GSI, your device must meet the following requirements:
For this codelab, you will use a Pixel 3 phone as an example, which fulfills all of these device requirements, but you can use other newer Pixel devices as well.
For devices from other manufacturers, you can check whether the device is Treble-compliant by using the commands that are described later in this codelab, and you can check the device's manufacturer's website for information about unlocking the bootloader and flashing system images.
During this codelab you'll be doing a clean install of a GSI. This process erases any local user data on the device. Make sure to back up your data before installing a GSI on the device.
Also, note that GSIs are not intended for everyday use. GSIs are provided for testing only and lack some capabilities that are essential to daily usage phones. After you've installed a GSI, you'll need a factory image build from your device manufacturer to flash back to your everyday build.
In this codelab, you're going to:
Although it's not covered in this codelab, after installing a GSI, you can perform app testing and validation.
platform-toolsdirectory added to your
setx path "%path%;%your-android-sdk%\platform-tools"
Before you can install a GSI onto the Pixel 3, you need to set it up.
Follow the instructions to enable USB debugging on the Pixel 3, then type the following command in a terminal:
You should see your test device's serial number listed in the terminal.
Starting with Android 9 (API level 28), all new launched devices are Treble-compliant. To confirm that your test device is launched with Android 9 (API level 28) or higher, type the following command:
adb shell getprop ro.product.first_api_level
If the result of this command is 28 (or higher), you are ready to go.
Note: GSIs for older versions of Android can't be installed on devices running newer versions of Android. For example, you can't install an Android 10 GSI on a device that launched with Android 11.
To flash a GSI onto your test device, you need the
fastboot tools. We recommend that you use the version that matches the current running Android version on your Android device.
To determine the version of your SDK's platform tools, run the following command:
The steps you need to take to unlock your devices' bootloader depend on your device's manufacturers.
In this codelab, you're using a Pixel 3, which was the first set of Pixel devices that launched with Android 9 (API level 28) or higher. However, these steps will work for any Pixel 3 and higher device:
adb reboot bootloader
fastboot flashing unlock
ThisPixel 3 is now ready to install a GSI.
For more information about unlocking or relocking the bootloader on Pixel devices, see Unlocking the bootloader.
All of the GSIs that are available are listed on the Android Generic System Images (GSIs) page. GSIs are grouped by CPU architectures. To check the CPU architecture for your device, run the following command in a terminal window:
adb shell getprop ro.product.cpu.abi
It should return one of the following:
By default, the Pixel 3 is running in the
arm64-v8a architecture mode, so you can use either of the following GSIs:
If your app uses Google Play Services, you need to use a GSI that includes Google Mobile Services to test your app. However, to minimize the download file size, in this codelab you'll use the ARM64 GSI; the steps are exactly the same for GSIs that include Google Mobile Services.
GSIs are a part of the Android release cycles including the Developer Preview, Beta, and the final release. At the final release, the GSI source code is released to AOSP. The following table summarizes where to get GSIs, depending on the phase in the Android release cycle::
Developer Preview or Beta
aosp GSI on CI page:
aosp GSI on CI page:
You're downloading an Android 11 GSI, which is currently in the Beta phase, so the GSIs are only available on the GSI release page. Follow these steps to download the ARM64 GSI from there:
mkdir ~/gsi cd ~/gsi mv ~/Downloads/aosp_arm64-exp*.zip . unzip aosp_arm64-exp*.zip
You should see 2 image files after unzipping the file:
Steps for installing a GSI are heavily dependent on the device that you are using because different Android device manufacturers have their own flashing tools and instructions. In this codelab, you're installing the GSI onto a Pixel 3 device. For other devices, visit the device's manufacturer site to find the tools and processes for that device.
In this codelab, you will use a Pixel 3 running Android 9 to install GSI: Android 9 launched phones are more accessible than Android 10 launched devices at current time.
The tools needed to install the GSI on your Pixel 3 are
fastboot. Let's get started:
adb reboot bootloader
fastboot flash system system.img
fastboot flash --disable-verification vbmeta vbmeta.img
fastboot -w reboot
After a minute or so, your device should boot into the newly-installed Android 11 GSI.
Although you used a Pixel 3 device that is running Android 9 to install the GSI, if you wanted to use a Pixel 3 or 4 device that was running Android 10, there are a few additional things to consider. Android 10 introduced dynamic partitions which affects GSI installation in the follow aspects:
Pixel 3 or 4 devices that are running Android 10 must be put into fastbootd (dynamic fastboot) mode, instead of regular fastboot mode, when dynamic partitions are enabled.
adb reboot fastboot // Command to use when dynamic partitions are enabled
adb reboot bootloader // Command to use when dynamic partitions are not used or are disabled
You can check the
dynamic_partition boot device property to see whether dynamic partitions are enabled or disabled:
adb shell getprop ro.boot.dynamic_partitions
The command returns
true if dynamic partitions are enabled.
When dynamic partitions are enabled, the system partition is one of the dynamic partitions. GSIs are installed into this dynamic system partition. Sometimes, a GSI's size might be bigger than the existing
system partition size. In this case, you need to delete some other dynamic partitions such as the
product partition to make more space for the GSI when the system resizes the system partition:
fastboot delete-logical-partition product_a|product_b
See the official documentation page for more information about when to choose
Manually installing GSIs can be demanding for some devices. Starting in Android 10, the platform includes a feature called Dynamic System Updates (DSU), which makes it much easier to install GSIs on devices that support the feature:
DSU is available on Pixel 3 or higher devices that run Android 10 or higher. This codelab demonstrates the manual process of installing a GSI on a device that runs Android 9, but after you've finished with this codelab we encourage you to check out the DSU page to learn more about other ways to install GSIs for devices that run Android 10 or higher and support DSU.
Congratulations! You've finished this codelab and you now have a fresh GSI image running on your Android phone.
In this codelab, you learned how to:
As a testing platform, Android GSIs enable you to do the following things:
We love hearing your feedback about GSIs and Android! Share your thoughts and report GSI issues by filing GSI bugs, discussing topics on StackOverflow, and contributing to the GSI page on Reddit!