LineageOS for QEMU Virtual Machines

LineageOS builds for running Android VM on

• any macOS/iOS device (via UTM), or
• generic libvirt QEMU virtual machines

For the latest CI release, see releases.

Usage

• For first time installs, download UTM-VM-lineage-*.zip from releases and unzip.

• To install an update package, boot into LineageOS Recovery, select Apply update, then Apply from ADB. Use lineage_virtio_arm64only-ota.zip from releases if updating to a new LineageOS build, or use your own update package. On the host, run

adb sideload [lineage_virtio_arm64only-ota.zip|*.zip]

Android Debug Bridge (ADB)

These targets offer ADB access over Ethernet or VirtIO VSOCK. If running on macOS/iOS devices (via UTM), ports 5555 and 5554 (for adbd and fastbootd) are forwarded to the host device by default via Emulated VLAN. This means you can connect via

adb connect $HOST_IP

fastboot -s tcp:$HOST_IP [flash|reboot|...]

If running adb on the same host, no further configuration is needed and the device will be automatically detected as an emulator.

Bypassing Signature Verification in Recovery

LineageOS Recovery supports sideloading unsigned update files. To allow this, you need to install a non-release version of the recovery image. To put the device in fastbootd, boot into LineageOS Recovery, select Advanced, then Enter fastboot. On the host, download recovery-userdebug.img from releases and run

fastboot -s tcp:$HOST_IP flash recovery recovery-userdebug.img

Installing Google Apps

If you choose to install Google apps, they must be installed immediately after a factory reset (or at first boot) via recovery. Additionally, you need to first bypass signature verification in recovery.

Follow the instructions to install an update package. Use the Google apps package for the Mobile, ARM64 variant.

Installing Magisk

To install Magisk, download the boot.img from releases and patch it on a running instance of this LineageOS build following the instructions. Pull the patched image magisk_patched*.img from the device, put the device in fastbootd, then run

fastboot -s tcp:$HOST_IP flash boot magisk_patched*.img

Building

This repository provides the build script to compile LineageOS on the latest Ubuntu, and assumes you already have root access via sudo with apt and git in your $PATH. It may also work with other Linux distributions, but these configurations are not tested.

To build these images yourself via CI (e.g. GitHub Actions), fork this repository, then go to Actions, select Build, and select Run workflow. Under Runner, you can either use a GitHub-hosted runner by entering ubuntu-latest, or self-hosted for your own hardware.

Credits

• LineageOS
• 0xCAFEBABE