Android Generic System Image is pure Android OS without vendor-specific customizations; it includes the core OS functionality for all of the same Android OS generation running on devices supporting Treble (which includes Android 9 Pie and above). After validating that applications function normally on GSI, the apps are guaranteed to work on all devices with the same version of Android OS. GSI could also be built once and used for multiple compatible devices: one build applies to all.

This codelab teaches you how to build a GSI and flash it to an Android device. Alternatively, you can skip the building GSI section, download a prebuilt GSI, and go directly to the "flashing the GSI" section.

What is Generic System Image (GSI)?

Android GSI is a tool to enable developers to perform early application development and validation on future Android OS versions: if an application works on GSI, it should execute smoothly on future certified OEM platforms that have the same Android API level.

Project Treble makes the Android GSI project possible. Treble creates a clean interface between the hardware platform and Android OS

An OS built with full Treble compliance would behave consistently on the fully Treble-compliant devices. A Generic System Image (GSI) is a fully Treble-enabled Android OS:

Android devices launched with Android 9 Pie are guaranteed to be fully Treble-compliant. With a device launched with Pie and above, you can load any future Android GSI images.

This codelab will walk you through creating your own GSI or downloading from the AOSP/GSI beta site, and installing it to your Android device. The Android Pie GSI is used as an example, but the concepts and steps are applicable to future Android GSI versions.

What you will build

In this codelab, you're going to:

  • Download GSI
  • Build GSI from source code
  • Install GSI to Android devices

From that point on, you would do your application development and validation as usual, as GSI is the OS.

What you'll learn

What you'll need

This codelab is focused on building and flashing GSI. It does not go into detail about concepts and background knowledge.

Follow the instructions on developer.android.com to enable your Android device for USB debugging:

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

Flashing GSI requires your Android device's bootloader to be unlocked. Different Android devices may have different instructions and tools for unlocking the bootloader. Refer to your device's manufacturer or carrier for details.

This codelab uses Pixel 3, so to unlock the bootloader, do the following:

  1. On your device, click or tap Settings > System > Developer Options > OEM unlocking, and then tap to enable if not already enabled.
  2. Android Q introduces the new dynamic partition feature. When enabled, you need to perform flashing in the combined fastboot and recovery mode. In terminal, enter the following:
    adb shell getprop ro.boot.dynamic_partitions
    This checks the "dynamic partition" status:
    true: dynamic partition is enabled (for Android Q and after)
    false: dynamic partition is NOT enabled (for Android 9 and before).
    Make a note of this state, as it decides what command to use to flash your GSI later in this codelab.
  3. Enter fastboot or userspace fastboot mode. On Linux host, inside terminal, enter the following:
    adb reboot fastboot [if dynamic partition is not enabled ]
    or
    adb reboot bootloader [for dynamic partition]
  4. To unlock the bootloader, inside terminal, enter:
    fastboot flashing unlock
    fastboot reboot

Check for GSI compatibility

GSI is part of Project Treble, and requires fully Treble-compatible devices. Treble is a mandatory feature for Android 9 Pie and above. This codelab uses Pixel 3, which is launched with Android 9 Pie, so it meets the GSI requirement.

If you are not sure whether your device is fully compliant with Project Treble, the following steps, executed inside the terminal window, help to confirm compliance:
adb shell getprop ro.treble.enabled ⇒ returns true
adb shell cat /system/etc/ld.config.txt
...
[vendor]
⇐ check this section
namespace.default.isolated = true

If the above line is false,it means that vendor code might call some private OS functions. That indicates that it is not Treble compliant, and you cannot use GSI on this device.

Decide the GSI type

CPU architecture

Your Android device's CPU architecture decides GSI's architecture. They must match. To determine the device's $arch-type, use the following command:

adb shell getprop ro.product.cpu.abi

It should return one of the following:

For Pixel 3, it is arm64-v8a, which corresponds with the 64-bit ARM platform.

GSI vs. Legacy GSI

If "system" is not running as root on the device, you must use legacy GSI. In AOSP image, legacy GSI is tagged as "_ab" in the image's lunch menu. Check the status of system-as-root with:

adb shell cat /proc/mounts | grep -q /dev/root && echo "system-as-root" || echo "non-system-as-root"

For Pixel 3, it returns "system-as-root", you could use non-legacy GSI. Note that legacy GSI would also work for system-as-root device, in that case, you just include some extra code not needed for your device.

Build Variant

GSI is a development tool, so you build a userdebug variation, which enables you to see more debugging messages.

In the preceding sections, you have determined what GSI to build. For Pixel 3, it should be arm64-userdebug. The equivalent lunch menu to build is aosp_arm64-userdebug

Download Android Q GSI

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

For Pixel3, both ARM64+GMS and ARM64 would work. They are all -user flavor builds. For this codelab's purpose, download ARM64 without GMS.

Continue to the Flashing GSI section to flash the image onto a Pixel 3, or continue to the next section to read how to download the Android Pie GSI source and build an image from the source.

Downloading Android Pie GSI

AOSP master and GSI has their own Continuous Integration (CI)! To download Android 9 Pie GSI from the Android 9 Pie GSI CI page, do the following:

export PATH=$HOME/pie-gsi:$PATH

You now have everything you need to flash Pie GSI onto the Pixel 3 device. Continue to the Flashing GSI section to continue. If you would like to build your own GSI, or your GSI type is unavailable on Pie-GSI CI page, continue to the next section.

You should follow the instructions on the AOSP for this step, except that you can use simplified steps on a Pixel 3.

Download the Code

GSI source code is part of AOSP. From Android Pie forward, GSI has its own branch for each equivalent Android OS, named ${dessert-name}-gsi; for Android Pie, it is pie-gsi.

To download the source code for pie-gsi, enter the following commands:

mkdir -p ~/source/pie-gsi && cd ~/source/pie-gsi

repo init -b pie-gsi -u https://android.googlesource.com/platform/manifest

repo sync -c

This may take a fair amount of time, depending on your Linux system performance and Internet connection.

Build GSI

Using the following two steps, you build your GSI:

  1. Set up the lunch menu as decided from the step in the earlier section, "Finding the Matching GSI Type," by entering the following commands:

source build/envsetup.sh

lunch aosp_arm64-userdebug

  1. Build the GSI image by entering the following command:

make -j

These steps may take 30+ minutes, depending on your Linux system performance. GSI branches are well-maintained, so it should build successfully. If you do experience failures, please file a bug for GSI.

Congratulations! Your GSI should be built into 2 files:

out/target/product/generic_arm64/system.img

out/target/product/generic_arm64/vbmeta.img

where:

Note that this section is heavily device-dependent. OEMs may have their own flashing tools and instructions. Refer to your device's manufacturer for details. The general process is the same across devices, though. You will load GSI onto the device and then reboot.

For Pixel 3, the tools you will use are:

When GSI is built, those tools also get built inside the Android source tree and they are in the $PATH already. If you downloaded GSI, you also downloaded these two utilities at that time and added them to the $PATH. In both cases, the tools are ready to be used. For Android Q experimental GSIs, you would use the latest tool inside your SDK, so make sure ${your-sdk-location}/platform-tools is added to the $PATH.

The flashing steps are the same except for the location of the GSI:

  1. Make sure you are in the same directory where GSI is.
    For downloaded Q GSI: cd ~/q-gsi
    For downloaded Pie GSI: cd ~/pie-gsi
    For built Pie GSI from source: cd $ANDROID_PRODUCT_OUT
  2. Enter the flashing mode.
    If dynamic partition is enabled, enter the following command:
    adb reboot fastboot
    Otherwise, enter the following command: adb reboot bootloader
  3. Flash GSI using the following commands:
    fastboot flash vbmeta vbmeta.img
    fastboot flash system system.img
  4. Reboot (with erasing userdata) using the following commands:
    fastboot -w reboot

Warning: You erase user data on the device when you boot up GSI. You will get a fresh GSI device for your application development. This also means that you lose everything previously saved on this device.

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

That's it! You have a fresh GSI running on your Android device! Now you can start your development on the new OS, GSI.

Summary

In this codelab, we have covered:

As a tool, GSI enables developers to:

Starting from Android 9 Pie, GSI branches are maintained on AOSP. You can download GSI binaries from AOSP CI site or the GSI beta site, making it much easier to install.

Further reading

We encourage developers to use GSI as the application vehicle for early application development and validation. Having the OS and your applications working together will produce a better and healthier Android ecosystem. Let GSI work for you!

Got some ideas or found issues about GSI? Please file GSI bugs. We appreciate your efforts for making a better GSI!