Treble (which includes Android Pie and above) creates a clear interface between Android OS and Vendor portion. The OS part is called Android Generic System Image(GSI):

Android OS builds conforming with Treble interface would be able to run on any Treble compliant Android device. On the other hand, GSI would miss all of the cutting-edge OS customizations from Pixel and other OEMs.

GSI provides values to application developers in that: at OS beta time, developers would be able flash to previous generation(s) devices, develop and validate application earlier than before, which would enable:

In short, GSI brings the precious time for application developers, and a better Android OS and ecosystem.

This codelab teaches you how to flash Android Q experimental GSI to an Android 9 ( API level 28 ) device, and start our development on Android Q on it.

What is Generic System Image (GSI)?

Android GSI is a full OS image that matches with AOSP source code. To application developers, GSI is a tool, similar to emulator, to enable developers to perform early application development and validation on future OS versions: if an application works on GSI then it should execute smoothly on future certified OEM platforms that have the same Android API level.

Device Requirement for Android GSI

In order to use Android GSI, devices need to be fully Treble compliant; Treble support is mandatory for devices launched with Android 9 and above. In fact Android devices launched with Android 9 and later are required to be 2 future generations GSI compatible ( but it is not required for devices to be able to run previous generation GSIs).
Installing GSI needs to unlock bootloader and flashing tools specific for the devices, the tools and procedures are from device manufacturers. We use Pixel 3 device as an example: we walk through the steps to install Android Q GSI onto Pixel 3.

What you will build

In this codelab, you're going to:

  • Identify the right Android Q GSI to download
  • Install Android Q GSI to Android devices

From that point on, you could do our application development and validation as usual: Q GSI is the OS.

What you'll learn

What you'll need

Enable USB Debug

Follow instructions on to enable our Android device for USB debugging:

  1. Settings > System > About phone, tap "Build number" for 7 times
  2. Settings > System > advanced > Developer options > USB debugging, tap to enable it.
  3. Connect our device physically to our host computer via USB cable, "allow USB debugging" when prompted on our Android device.
  4. In a terminal type: $adb devices
    you should see our device's serial number listed in terminal.

Confirm Device launching OS

we knew that Pixel was launched with Android 9 Pie, it is not necessary, but let's confirm it: in side terminal, execute an adb command

adb shell getprop ro.product.first_api_level

28 -- which is Android 9, we are ready to go.

Full GSI types are documented on AOSP, Android Q GSI, at beta time, are released with 2 types, 3 binaries:

Pixel 3 is arm64 cpu architecture, so we could use arm64 GSI. but let's confirm it: inside terminal window, do

adb shell getprop ro.product.cpu.abi

It should us return one of the following:

for Pixel 3, it is arm64-v8a, so we could use either ARM64 or ARM64+GMS, the difference is that the latter including most GMS applications. For simplicity purpose, we use ARM64 GSI binary here.

Note: ro.product.cpu.abilist includes all supported architecture types for our device.

Download Android Q GSI

Android Q experimental GSIs are released at Android Q preview time:

For this codelab with Pixel 3, we would use ARM64 without GMS to save some download time

mkdir  ~/q-gsi
cd ~/q-gsi
mv ~/Downloads/aosp_arm64-exp-QPP*.zip ./
unzip   aosp_arm64-exp-QPP*.zip
which adb
adb --version

Please note that this part is heavily device dependent: different Android device manufacturers would have their own flashing tools and instructions, our device manufacturer's website is our ultimate resources. But the theory is the same and simple: load GSI onto the device and reboot, just in different format!

For Pixel 3 and Mi Note 7, the tools we will use are:

They are inside our Android SDK's platform-tools directory, just make sure the path is inside our $PATH directory.

Let's start the fun part - flashing Android Q to this Android 9 phone:

  1. Make sure you are in the same directory where GSI is
cd ~/q-gsi
  1. Enter flashing mode
adb reboot bootloader
  1. Flash GSI
fastboot flash vbmeta vbmeta.img
fastboot flash system system.img
  1. Reboot (with erasing userdata)
fastboot -w reboot

Note that we have erased user data on the device when we boot up GSI: we get a fresh Android Q GSI device for our application development: make sure anything precious on the device already backed up before flashing GSI!

In a minute or so, Android Q GSI boots up and you should see:

There it is: you have got a fresh Android Q GSI running on an Android Q phone! Now you could really start our development on Android Q, and report Android Q GSI issues.


In this codelab, we have covered:

As a development tool, Android GSI enables developers to:

Use GSI to our favor and let GSI work for us!

Further reading

We love your feedback for GSI and Android, share ideas or found issues about GSI at file GSI bugs, stack overflow, reddit, we appreciate your efforts for a better GSI!