If you've only heard of Project Treble in passing but haven't looked into it all that much, then you may have heard that it's supposed to help major Android updates roll out more quickly. At XDA, there's another benefit that we've spoken about at length: the ability to boot an AOSP Generic System Image (GSI) on any supported device. This means that devices that were once running heavily customized Android versions like Samsung Experience on the Samsung Galaxy S9 or EMUI 8 on the Huawei Mate 10 Pro can alternatively run software closer to that of the Google Pixel 2.

After-market custom ROMs (customized versions of Android software that are made by independent developers usually not affiliated with a company) are a big draw to the XDA forums, and thanks to the changes in Android that Project Treble require, Treble-supported devices will have an easier time flashing custom ROMs based on the Android Open Source Project (AOSP). Without Project Treble, developers have to employ a lot of tricks and hacks to get their custom ROMs working, and while Treble support doesn't solve everything, it certainly helps kickstart the process.

Devices like the Huawei Mate 9, Honor View 10, Huawei Mate 10 Pro, Honor 7X, Exynos Samsung Galaxy S9, or Allview V3 Viper would have had either no AOSP-based custom ROMs available due to lack of developer interest or ROMs lacking some basic hardware functionality. But as we've seen with the in the case of each of these devices, the ROMs that are available thanks to Treble support are mostly functional (there are some differences in terms of what works and what doesn't, and the community has put together a wiki page you should check out to find that information).

Since Treble is so new to users and the process to flash them is a little different compared to the usual custom ROMs, there's been a lot of confusion about how to flash a GSI onto a Treble-compatible device. This tutorial will broadly walk you through how to flash such a ROM. There may be a few different steps involved depending on the device, but in general, the process should be similar. Here's how to flash a GSI on a Treble-compatible Android device.


How to flash a Generic System Image on a Project Treble-supported device

Requirements:

  • Your device MUST have an unlockable bootloader.
  • Your device MUST be Project Treble compatible. That means your device meets one of the following criteria:
    • Your device LAUNCHED with Android 8.0 Oreo or a newer version (eg. Android 8.1 Oreo) AND is Google Play certified. (If you rooted your device/flashed another custom ROM and somehow ended up with your device being listed as uncertified in Google Play, then don't worry. We're only concerned about the status of the device as it was shipped.)
    • Your device UPGRADED to Android 8.0 Oreo or a newer version AND was made Project Treble compatible by the manufacturer. See this article for a list of such devices.
    • Your device does not meet either of the above criteria but DOES have access to an unofficial way to be made Treble compatible. Again, refer to this article for a list of such devices.
  • Your device is free of any heavy modifications such as the Xposed Framework, SuperSU, or Magisk. You can re-install these afterwards, but please be sure you are using the stock boot/ramdisk before proceeding.

Devices such as the Samsung Galaxy S8/S8+ (Exynos or Snapdragon), Samsung Galaxy Note 8 (Exynos or Snapdragon), LG V30, Sony Xperia XA1 series, and more do not meet any of these criteria and thus cannot follow this guide. While 2018 Nokia-branded devices and the Snapdragon Samsung Galaxy S9 launched with Android Oreo and are Treble-supported, they do not have unlockable bootloaders and hence cannot flash GSIs.

Please be sure that, even if your device is listed as Treble-compatible, that you do not follow this guide unless you have actually received the Android Oreo update either officially or unofficially. If your device meets the above criteria, then you're almost ready to flash a GSI. The last thing that we need to say is that flashing a GSI will require you to factory reset your device, so be sure you're prepared to lose app data before you proceed with this! We recommend you make an off-device backup (such as on your PC or an SD Card) in case anything goes wrong.


Guide to flash GSI on devices that support Project Treble

Preparation for devices that officially support Treble

  1. Unlock the bootloader of your device. The steps you take here are different depending on your device. We have many guides available both on the Portal and in our forums for you to peruse. Just do a quick Google search for "XDA unlock bootloader" + your device name and you should find many guides.
  2. Download the GSI of your choice onto your PC. You can either flash a pure AOSP ROM such as phh-Treble, or if you prefer more features you can grab other ROMs like LineageOS 15.1 or Resurrection Remix GSIs. I have linked the threads as follows. Download the right image for your device type (ARM64 for most of you) and partition type. If your device supports seamless updates (a list of such devices can be found here), then download the A/B image, otherwise download the A-only image.

Preparation for devices that unofficially support Treble

  1. Unlock the bootloader of your device. The steps you take here are different depending on your device. We have many guides available both on the Portal and in our forums for you to peruse. Just do a quick Google search for "XDA unlock bootloader" + your device name and you should find many guides.
  2. Make your device Treble compatible by flashing the appropriate files linked in the posts mentioned in this article. You MUST do this before you can flash a GSI!
  3. Download the GSI of your choice onto your PC. You can either flash a pure AOSP ROM such as phh-Treble, or if you prefer more features you can grab the LineageOS 15.1 or Resurrection Remix GSIs. I have linked the threads as follows. Download the right image for your device type (ARM64 for most of you) and partition type. If your device supports seamless updates (a list of such devices can be found here), then download the A/B image, otherwise download the A-only image.

The following steps depend on whether or not your device has a functional TWRP that you can use. If your device has TWRP, then we highly recommend you install that first. We have a guide for that here.

Flash GSI with TWRP

  1. Perform a factory reset within TWRP.
  2. Transfer the GSI from your PC to your device's internal storage where TWRP can access it.
  3. Tap on "Install."
    How to flash a Generic System Image GSI on Project Treble devices
  4. Change the type from "zip" to "image."
    How to flash a Generic System Image GSI on Project Treble devices
  5. Find and select the GSI you downloaded.
  6. Choose to flash to the system partition.
    How to flash a Generic System Image GSI on Project Treble devices
  7. Once that is done, reboot your device.

Hopefully, your device should boot up after a few minutes of waiting. If not, skip the following section and go to the troubleshooting tips.

Flash GSI without TWRP

  1. Perform a factory reset on your device. You have two options here:
    • Open the settings app on your phone and look for the factory reset option. It's usually under settings related to backup.
      How to flash a Generic System Image GSI on Project Treble devices
    • Reboot to your device's stock recovery using either a button combination when booting or issuing the following ADB command when booted in Android: adb reboot recovery. Once here, use the volume keys to navigate and the power button to select the factory reset option.
  2. Once your device has been factory reset, reboot to your device's bootloader using either a button combination when booting or issuing the following ADB command when booted in Android: adb reboot bootloader
  3. With your device connected to your PC, open up a command prompt or terminal window in the same directory where you downloaded your GSI of choice.
  4. Enter the following command: fastboot erase system
  5. Enter a command in the following format: fastboot -u flash system name_of_system.img
  6. Allow the image to flash, it could take a few minutes. Once it has completed, reboot your device either manually via power key or by entering fastboot reboot.

Hopefully, your device should boot into your GSI of choice. If not, here are some troubleshooting tips.

Troubleshooting Tips

  • On some devices like the Google Pixel 2/2 XL, Android Verified Boot (AVB) needs to be disabled. You can do so by flashing this image to the vbmeta partition (command: fastboot flash vbmeta name_of_vbmeta.img)
  • On the OnePlus 6, you'll need to follow some special flashing instructions.
  • It's possible that dm-verity is preventing your device from booting with the GSI. In that case, please go ahead and flash Magisk and then see if it boots. I'm told that this is required for the Razer Phone, for instance.
  • As a last resort, you can try a full format of the data partition (WARNING: THIS WIPES EVERYTHING) by entering fastboot -w from a command prompt/terminal window while in the bootloader. I have had to do this on my Huawei device before it could work.

What to do after flashing the Generic System Image

By default, there isn't any app to manage superuser privileges. You can fix that by installing phh's SuperUser from the Google Play Store. Alternatively, you can flash Magisk or SuperSU—it's up to you.

Next, you can install Substratum for themes or the Xposed Framework if you want further modifications. The Magisk repository has a ton of neat modules you can try as well. LineageOS 15.1 and especially Resurrection Remix already offer a ton of features out of the box, so we don't believe you'll really need to tinker with a ton of extra goodies, but the choice is there.

Now, enjoy the world of stock Android! We recommend you follow the Treble-Enabled Device Development forum for any updates on your ROM. Also, follow the XDA Portal for all the latest developments related to Project Treble. The best way to do so is to set up a feed for the Treble tag.

Lastly, please contribute to the Treble Experimentations wiki page so others will know about any potential issues with the ROM (and so developers will know what to fix!)