A generic system image (GSI) is a "pure Android" implementation with unmodified Android Open Source Project (AOSP) code.
Starting with Android 9 (API level 28), a Generic System Image (GSI) is available that you can run on actual devices rather than just on an emulator, making app testing easier and more consistent for developers. The GSI images are open-sourced.
How is GSI useful for developers?
GSI is a benchmark for compliance. It provides a consistent testing environment for developers on any compliant device. If your app works on GSI, you can be certain it also works on almost all Android devices.
Also, starting with Android 9 (API level 28), Android compatibility ensures system images are backward-compatible with previous vendor implementations. This means that developers can flash future versions of the Android platform onto their current devices that are running vendor implementations of Android 9 to do the following:
- To develop apps using new Android features.
- To validate existing apps for forward compatibility.
Core system functions maintain their behavior across platform versions. However, you might encounter behavioral differences in the following situations:
- Interactions that involve the UI.
- Workflows that use new hardware features.
Check devices for compliance
GSI works only on devices with the following characteristics:
- They are unlocked.
- They have Treble support.
- They were launched with Android 9 (API level 28) or higher. Devices upgraded to Android 9 from an earlier version may or may not support GSI.
To determine whether your device can use GSI and determine which GSI OS version you should install, do the following:
Check for Treble support by running the following command:
adb shell getprop ro.treble.enabled
If the response is
false, the device isn't compatible with GSI and you shouldn't continue. If the response is
true, continue to the next step.
Check for cross-version support by running the following command:
adb shell cat /system/etc/ld.config.version_identifier.txt \ | grep -A 20 "\[vendor\]"
In the output, look in the section
If the value for that attribute is
true, then the device fully supports Vendor Native Development Kit (VNDK) and can use any GSI operating system (OS) version. Choose the latest GSI OS version available.
If the value for the attribute is
false, then the device isn't fully VNDK-compliant, and the device can use only the GSI for the same on-device OS version. For example, an Android 9 (API version 28) device that isn't VNDK-compliant can load only an Android 9 GSI image.
The GSI CPU architecture type must match the device’s CPU architecture. To find the right CPU architecture for the GSI image, run the following command:
adb shell getprop ro.product.cpu.abi
Use the output to determine which GSI image to use when flashing your device. For example, on a Pixel 3, the output would indicate that the CPU architecture is
arm64-v8a, so you would use the
arm64type of GSI.
For devices that were upgraded to Android 9 from an earlier version, there are two different types of legacy GSI images available:
_ab. The system user's privilege level on the device determines which type to use.
To determine the system user’s privilege level, run the following command:
adb shell cat /proc/mounts | grep -q /dev/root && echo "system-as-root" || \ echo "non-system-as-root"
If the output of the command is
system-as-root, you must use the
_abtype of GSI image. If the output is
non-system-as-root, you must use the
_atype. If neither value is in the output of the command, the device isn't compatible with GSI and you shouldn't continue.
Install GSI images
After you have determined that your device is compatible with GSI, get GSI binaries that corresponds to your device one of the following ways:
- Android Q experimental GSI — Download from the Android Q GSI release site
- Android 9 (API level 28) GSI — Download from the AOSP CI site or build from AOSP sources
Next, flash the image onto your device, which could be done in one of the following ways:
Give us your feedback
GSI images help to validate apps on Android. We appreciate your feedback on the images, the tools, and the process of enabling GSI on your devices.
To notify us of bugs or feature requests, use the dedicated issue tracker component.