Generic System Image

A Generic System Image (GSI) is a pure Android implementation with unmodified Android Open Source Project (AOSP) code, runnable on a variety of Android devices.

GSI support across devices

Figure 1. GSI support across devices.

Starting with Android 9 (API level 28), Generic System Images (GSIs) are available to app developers throughout the full Android release cycle. You, as an app developer, can install and run the latest Android GSIs on a variety of existing Android devices, and in different Android OS release stages including Preview and Beta phases, to perform app testing! In this way, your app gets broader test coverage, starting at an much earlier time than before:

  • More test coverage on real devices
  • More time to fix app compatibility issues
  • More opportunities to fix non-compatible issues in Android OS reported by app developers

Note: You would install a later GSI version than the version of Android currently installed on a device.

The GSI project helps improve the Android ecosystem by providing more ways to improve app and OS quality before the next release of the OS. The project is also open-sourced.

GSI includes core system functionalities in all devices running Android 9 and above; in other words, GSI does not include device manufacturers's customizations. You might encounter behavioral differences in the following situations:

  • Interactions that involve the UI.
  • Workflows that request newer hardware features.

Check device compliance

GSI works only on devices with the following characteristics:

  • Bootloader is unlocked.
  • Fully Treble-compliant.
  • 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 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 newer than the on device 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.

Download GSI images

These versions of GSIs here are not to be used by OEMs to run and submit compliance tests. OEMs should continue to refer to their existing communication channels, such as their Technical Account Managers for compliance test related activities.

There are a few ways to get GSIs, depending on your development needs:

  • For Android 10 GSI images, download from the GSI release page.
  • For Android 9 GSI source code, download from AOSP and build your GSI images.
  • For pre-built GSI images without GMS applications, download from the AOSP CI site.

Install GSI images

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

Installing GSI is device-dependent. Refer to your device's manufacturer for the exact tools and procedures. For Pixel 3 and newer devices, there are several ways to install:

  • Manually flashing GSI images — see Flashing GSIs
  • Using Dynamic System Update (DSU) for devices that already run Android 10 — see the Dynamic System Update site
  • 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.

    Additional resources