How to Inspect Dynamic System Updates and GSI Images on Android Using ADB dumpsys dynamic_system

Testing early developer previews, evaluating system updates, or validating applications against untainted Android Generic System Images (GSIs) traditionally required flashing physical device partitions via fastboot. Flashing physical storage partitions carries significant operational overhead: it wipes local user data, risks bricking the boot chain, and requires complex flashing scripts. To streamline testing, Android introduced Dynamic System Updates (DSU) in Android 10. DSU allows developers to install and boot a secondary GSI into a temporary guest partition directly from the running host OS without wiping user data or unlocking the bootloader. Using the Android Debug Bridge (ADB), developers can query dumpsys dynamic_system to inspect active DSU sessions, partition allocations, and runtime states.

Understanding Android DSU Architecture

The Dynamic System Updates pipeline relies on native kernel loopback devices, Dynamic Partitions (super partition), and the dynamic_system system service:

• Temporary Guest Storage: DSU allocates virtual partition images (such as system_gsi and userdata_gsi) stored inside /data/gsi/ on the host user data partition.
• Dual-Boot State Machine: The system maintains state metadata tracking whether the device is running the standard host OS, has a GSI installed and staged for reboot, or is actively booted into the GSI guest environment.
• Zero-Risk Fallback: If the booted GSI crashes, fails to initialize hardware drivers, or encounters bootloops, a simple physical power cycle or hardware restart immediately reboots the smartphone back into the primary host OS without data loss.
• Session Lifecycle: DSU sessions can be persistent (retaining app state within the guest across reboots) or ephemeral (discarded upon rebooting back to host).

Connecting via ADB and Querying dynamic_system

To inspect the status of Dynamic System Updates, connect the target Android device with USB Debugging enabled under Developer Options:

# Verify device connection
adb devices

# Query the dynamic_system service dump
adb shell dumpsys dynamic_system

The output reports whether a DSU image is currently installed, active, or pending initialization.

Inspecting DSU Installation Status and State Flags

Filter the service dump to check current DSU operating flags:

# Inspect active state flags
adb shell dumpsys dynamic_system | grep -i -E "status|installed|enabled"

The service reports three primary lifecycle states:

Status State	Operating Condition	Operational Meaning
DISABLED	No GSI active	The device is running the native host OEM firmware with no DSU partitions mounted.
INSTALLED	Staged for reboot	A GSI has been downloaded and verified in storage; the next reboot will boot into the guest OS.
RUNNING	Active guest GSI	The device is currently executing inside the temporary Generic System Image environment.

Querying DSU via gsi_tool in ADB Shell

In addition to dumpsys, Android provides the dedicated gsi_tool command-line executable to query and govern DSU sessions:

# Query DSU status via gsi_tool
adb shell gsi_tool status

If a GSI is actively booted, gsi_tool status confirms:

running: true
installed: true

Auditing Staged DSU Partitions on Disk

When a DSU image is installed, Android creates sparse image containers under /data/gsi/. Inspect these partition allocations:

# Check allocated GSI partition images (requires root/system access)
adb shell ls -lh /data/gsi/dsu/

The directory typically contains:

• system_gsi.img: The mounted Generic System Image containing the clean AOSP system framework.
• userdata_gsi.img: The isolated storage boundary dedicated to applications and test data installed while running the GSI.

Enabling Persistent vs Ephemeral DSU Boots

By default, when a GSI is installed via the DSU loader, it boots in non-sticky mode. If the device restarts, it returns to the host OS. To make the GSI sticky (persisting across guest reboots until explicitly discarded):

# Enable sticky mode for the active GSI installation
adb shell gsi_tool enable -s

To reboot back into the primary OEM host system from within the running GSI:

# Disable the GSI and prepare host reboot
adb shell gsi_tool disable

# Reboot back to original host firmware
adb reboot

Tearing Down and Wiping DSU Guest Images

Once testing or benchmarking is complete, tear down the DSU environment to reclaim several gigabytes of host storage:

# Completely wipe the installed GSI image and guest userdata
adb shell gsi_tool wipe

Verify that the service returns to the clean unallocated baseline:

# Confirm DSU state is reset
adb shell dumpsys dynamic_system

Inspecting Dynamic System Updates via adb shell dumpsys dynamic_system provides mobile developers and OS engineers with absolute control over temporary system testing, eliminating the risks of bricked devices and destructive flash re-imaging.