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.

Introduction

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.

What is a Generic System Image?

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.

Why use GSIs for app compatibility testing?

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.

Device requirements for Android GSIs

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.

Back up any important device data

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.

What you'll do in this codelab?

In this codelab, you're going to:

  • Set up an Android device to use GSIs
  • Determine which GSI to use for your device
  • Download the GSI
  • Install the GSI onto an Android device

Although it's not covered in this codelab, after installing a GSI, you can perform app testing and validation.

What you'll learn

What you'll need

Before you can install a GSI onto the Pixel 3, you need to set it up.

Enable USB debugging

Follow the instructions to enable USB debugging on the Pixel 3, then type the following command in a terminal:

adb devices


You should see your test device's serial number listed in the terminal.

Check whether your device is Treble-compliant

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.

Check the version of your SDK's flashing tool.

To flash a GSI onto your test device, you need the adb and 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:

adb --version

Unlock your device's bootloader

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:

  1. Open your device's Settings app, then tap Developer options > OEM unlocking
  2. Reboot into the bootloader by holding down Power + Volume Down, or using the following adb command:
adb reboot bootloader
  1. Unlock the bootloader using fastboot:
fastboot flashing unlock
  1. Confirm the unlock on screen.

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::

Release phase

Location

GSI format

Developer Preview or Beta

GSI release page

Pre-built binaries:

  • aosp gsi
  • aosp + gms gsi

Final release

GSI release page

Pre-built binaries:

  • aosp gsi
  • aosp + gms gsi

AOSP

Source code:

  • aosp-android10-gsi
  • aosp-pie-gsi

aosp GSI on CI page:

Quarterly updates

AOSP

Source code:

  • aosp-android10-gsi
  • aosp-pie-gsi

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:

  1. Navigate to the image download table on the GSI release page.
  2. Select the download link for ARM64:

  3. Agree to the GSI terms and conditions, then download the file and unzip it:
  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 adb and fastboot. Let's get started:

  1. Navigate to the local directory where you unzipped the GSI image file.
cd ~/gsi
  1. Put the device into fastboot mode.
adb reboot bootloader
  1. Flash the GSI onto the device.
fastboot flash system system.img
  1. Disable AVB to allow the GSI to boot after installation.
fastboot flash --disable-verification vbmeta vbmeta.img
  1. Erase user data and the cache and then reboot:
fastboot -w reboot

After a minute or so, your device should boot into the newly-installed Android 11 GSI.

Additional considerations for Pixel devices running Android 10

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:

Flashing mode

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.

Partition resizing

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 product_a or product_b.

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.

Summary

In this codelab, you learned how to:

As a testing platform, Android GSIs enable you to do the following things:

Further reading

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!