Generic System Image

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.

GSI support across devices

Figure 1. GSI support across devices.

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:

  1. 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.

  2. 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 [vendor] for namespace.default.isolated.

    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.

  3. 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 arm64 type of GSI.

  4. For devices that were upgraded to Android 9 from an earlier version, there are two different types of legacy GSI images available: _a and _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 _ab type of GSI image. If the output is non-system-as-root, you must use the _a type. 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:

Note: If your device has adopted Android Verified Boot (AVB), download and flash the following image to disable AVB before flashing a GSI: vbmeta.img

Next, flash the image onto your device, which could be done in one of the following ways:

  • Using Dynamic System Update (DSU) for Pixel 3/XL devices: see Dynamic System Update site
  • Manually flashing GSI images — see Flashing GSIs
  • 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.