A Generic System Image, or GSI, is a build of Android's system partition that isn't tied to any specific phone model. It works because of Project Treble, which separates the Android OS framework from the vendor-specific hardware drivers underneath it. In practice this means one GSI build can run on phones from completely different manufacturers, as long as the phone's vendor partition speaks a compatible version of the interface Treble defines between the two layers.
Project Treble requires phones to expose a stable Vendor Interface (VINTF) between the system partition and the hardware-specific vendor partition. Phones that launched with Android 8.0 or later ship with this separation built in. A GSI targets a specific VNDK (Vendor NDK) version, and it will only boot correctly on a device whose vendor partition implements a compatible interface version — usually the same major Android version the GSI is built for, sometimes one version newer thanks to backward compatibility guarantees in the interface. Checking a device's Treble compliance and supported interface version before choosing a GSI avoids most boot failures.
GSIs are distributed in two variants matching the two partition layouts described in our dynamic partitions and super.img guide: an "A-only" build for devices with a single system partition, and an "A/B" build for devices with the seamless dual-slot layout. Flashing the wrong variant for your device's partition scheme is one of the most common causes of a GSI failing to boot, so confirm which layout your phone uses before downloading anything.
The general sequence, after confirming Treble compliance and downloading the correct A-only or A/B image:
fastboot devices sees the phone.fastboot erase systemfastboot flash system gsi.imgfastboot -wfastboot rebootOn A/B devices, the flash targets whichever slot is currently active; check the active slot beforehand with fastboot getvar current-slot if you need the other slot to remain on the original system image as a fallback.
Because a GSI's system partition doesn't match the signature the phone's stock verified boot chain expects, many devices need verity and verification disabled before a GSI will boot at all, rather than getting stuck at a warning screen or bootlooping. This is covered in more depth in our guide to fastboot flash vbmeta and disable-verity, which is frequently a required step immediately before or after flashing a GSI, not an optional one.
Bootloops immediately after flashing: almost always either a VNDK version mismatch between the GSI and the phone's vendor partition, or verified boot rejecting the unsigned system image. Confirm the vendor partition's interface version and check verity/verification status.
Flashed the wrong slot on an A/B device: use fastboot --set-active=other to switch the active slot back to the original system image without needing to reflash anything, then retry against the correct slot.
Cameras or cellular modem don't work after the GSI boots: this is expected on many devices, since a generic system image can't include vendor-specific proprietary blobs for every camera sensor or modem the OEM's vendor partition supports. GSIs are best suited for testing core Android functionality rather than as a daily-driver replacement for the stock ROM on every device.
fastboot reports an image size mismatch or "not enough space": the system partition on some devices is sized specifically for the stock ROM's footprint; a larger GSI build may not fit without first checking the partition size with fastboot getvar all.
GSI projects typically publish several build variants for the same Android version: a plain AOSP-style build, a build with Google apps/services included, and sometimes ARM64-only versus ARM64 plus 32-bit app support (arm64-ab versus arm64_binder64) variants. The 32-bit app support variant is noticeably larger and only matters if you still run older apps that were never updated to 64-bit-only builds; picking the smaller 64-bit-only variant is usually the better default unless you have a specific reason to need 32-bit compatibility. Mixing this variant choice up with the A-only/A/B partition choice covered above is a separate and equally common source of a GSI that won't boot.
The main use case is testing how an app or a new Android version behaves on close-to-stock AOSP, without the OEM skin's modifications to permissions handling, background process limits, or notification behavior getting in the way of what you're actually trying to observe. It's also a common path for keeping an older device that no longer receives OEM updates running a newer Android version, accepting the tradeoff of losing some hardware-specific features described above in exchange for current security patches and API levels.