Building and installing for libvirt QEMU virtual machine

Warning: The following build targets are not officially supported and are maintained by individual LineageOS maintainers. Due to this, unlike Emulator/AVD which is guaranteed to function when built, virtio build targets carry no such guarantee.

Warning: No virtio target is built by LineageOS build servers, and no OTA updates will be delivered to builds of these targets. As such, you must build all images and update the builds manually.

Known issues

Please note the following list of yet unresolved known issues when running LineageOS on a libvirt QEMU virtual machine:

Display color (only with Swiftshader graphics selected)
Video playback (only with Mesa graphics selected, which is the most common use case)

Introduction

If you would like to use LineageOS without setting up a physical device, try out Generic System Images (GSIs), or experiment with low-level Android components, this would be a good fit.

Tip: If your goal is to develop and debug Android applications, then using Emulator/AVD is the better option.

These instructions will help you build a LineageOS image that is suitable to run in libvirt QEMU virtual machine.

What you’ll need

A relatively recent x86_64 computer:
- Linux, macOS, or Windows - these build instructions are only tested using Ubuntu 20.04 LTS, so we recommend going with that.
- A reasonable amount of RAM (16 GB to build up to lineage-17.1, 32 GB or more for lineage-18.1 and up). The less RAM you have, the longer the build will take. Enabling ZRAM can be helpful.
- A reasonable amount of Storage (200 GB to build up to lineage-17.1, 300 GB for lineage-18.1 and up). You might require more free space for enabling ccache or building for multiple devices. Using SSDs results in considerably faster build times than traditional hard drives.
A decent internet connection and reliable electricity. :)
Some familiarity with basic Android operation and terminology. It may be useful to know some basic command line concepts such as cd, which stands for “change directory”, the concept of directory hierarchies, and that in Linux they are separated by /, etc.

Tip: If you are not accustomed to using Linux, this is an excellent chance to learn. It’s free – just download and run a virtual machine (VM) such as VirtualBox, then install a Linux distribution such as Ubuntu (AOSP vets Ubuntu as well). Any recent 64-bit version should work great, but the latest Long Term Support (LTS) version is recommended. There are plenty of instructions on setting up VirtualBox to run Ubuntu, so we’ll leave that to you. Though it is worth noting, if you already use either a Linux distro or macOS, you can just proceed.

Let’s begin!

Build LineageOS

Note: You only need to do these steps once. If you have already prepared your build environment and downloaded the source code, skip to Start the build

Install the platform-tools

If you haven’t previously installed adb and fastboot, you can download them from Google. Extract it running:

unzip platform-tools-latest-linux.zip -d ~

Tip: The file may not be named identically to what stands in this command, so adjust accordingly.

Now you have to add adb and fastboot to your PATH. Open ~/.profile and add the following:

# add Android SDK platform tools to path
if [ -d "$HOME/platform-tools" ] ; then
    PATH="$HOME/platform-tools:$PATH"
fi

Then, run source ~/.profile to update your environment.

Install the build packages

Several packages are needed to build LineageOS. You can install these using your distribution’s package manager.

Tip: A package manager in Linux is a system used to install or remove software (usually originating from the Internet) on your computer. With Ubuntu, you can use the Ubuntu Software Center. Even better, you may also use the apt install command directly in the Terminal.

To build LineageOS, you’ll need:

bc bison build-essential ccache curl flex g++-multilib gcc-multilib git git-lfs gnupg gperf imagemagick lib32readline-dev lib32z1-dev libelf-dev liblz4-tool libsdl1.2-dev libssl-dev libxml2 libxml2-utils lzop pngcrush rsync schedtool squashfs-tools xsltproc zip zlib1g-dev

For Ubuntu 23.10 (mantic), install libncurses5 from 23.04 (lunar) as follows:

wget http://archive.ubuntu.com/ubuntu/pool/universe/n/ncurses/libtinfo5_6.4-2_amd64.deb && sudo dpkg -i libtinfo5_6.4-2_amd64.deb && rm -f libtinfo5_6.4-2_amd64.deb
wget http://archive.ubuntu.com/ubuntu/pool/universe/n/ncurses/libncurses5_6.4-2_amd64.deb && sudo dpkg -i libncurses5_6.4-2_amd64.deb && rm -f libncurses5_6.4-2_amd64.deb

While for Ubuntu versions older than 23.10 (mantic), simply install:

lib32ncurses5-dev libncurses5 libncurses5-dev

Additionally, for Ubuntu versions older than 20.04 (focal), install also:

libwxgtk3.0-dev

While for Ubuntu versions older than 16.04 (xenial), install:

libwxgtk2.8-dev

Java

Different versions of LineageOS require different JDK (Java Development Kit) versions.

LineageOS 18.1+: OpenJDK 11 (included in source download)
LineageOS 16.0-17.1: OpenJDK 1.9 (included in source download)
LineageOS 14.1-15.1: OpenJDK 1.8 (install openjdk-8-jdk)
- NOTE: For building these versions you’ll need to remove TLSv1 and TLSv1.1 from jdk.tls.disabledAlgorithms in /etc/java-8-openjdk/security/java.security.
LineageOS 11.0-13.0: OpenJDK 1.7 (install openjdk-7-jdk)*

* Ubuntu 16.04 and newer do not have OpenJDK 1.7 in the standard package repositories. See the Ask Ubuntu question “How do I install openjdk 7 on Ubuntu 16.04 or higher?”. Note that the suggestion to use PPA openjdk-r is outdated (the PPA has never updated their offering of openjdk-7-jdk, so it lacks security fixes); skip that answer even if it is the most upvoted.

Python

Different versions of LineageOS require different default Python versions.

LineageOS 17.1+: Python 3 (install python-is-python3)
LineageOS 11.0-16.0: Python 2 (install python-is-python2)

If your default is python3, but you’re building branch that requires python2, there are various methods to using it, e.g. symlinking it manually or creating a virtualenv for it. We recommend the latter:

Generate the virtualenv once using virtualenv --python=python2 ~/.lineage_venv. Afterwards, activate it in each terminal where you need python2 as default by running ~/.lineage_venv/bin/activate.

The path ~/.lineage_venv can be chosen freely, this is just an example!

Create the directories

You’ll need to set up some directories in your build environment.

To create them:

mkdir -p ~/bin
mkdir -p ~/android/lineage

The ~/bin directory will contain the git-repo tool (commonly named “repo”) and the ~/android/lineage directory will contain the source code of LineageOS.

Install the `repo` command

Enter the following to download the repo binary and make it executable (runnable):

curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo

Put the `~/bin` directory in your path of execution

In recent versions of Ubuntu, ~/bin should already be in your PATH. You can check this by opening ~/.profile with a text editor and verifying the following code exists (add it if it is missing):

# set PATH so it includes user's private bin if it exists
if [ -d "$HOME/bin" ] ; then
    PATH="$HOME/bin:$PATH"
fi

Then, run source ~/.profile to update your environment.

Configure git

Given that repo requires you to identify yourself to sync Android, run the following commands to configure your git identity:

git config --global user.email "you@example.com"
git config --global user.name "Your Name"

Due to their size, some repos are configured for lfs or Large File Storage. To make sure your distribution is prepared for this, run:

git lfs install

To avoid duplicated Change-Id: trailers in commit messages, especially when cherry-picking changes, make Change-Id: a known trailer to git:

git config --global trailer.changeid.key "Change-Id"

Turn on caching to speed up build

Make use of ccache if you want to speed up subsequent builds by running:

export USE_CCACHE=1
export CCACHE_EXEC=/usr/bin/ccache

and adding that line to your ~/.bashrc file. Then, specify the maximum amount of disk space you want ccache to use by typing this:

ccache -M 50G

where 50G corresponds to 50GB of cache. This needs to be run once. Anywhere from 25GB-100GB will result in very noticeably increased build speeds (for instance, a typical 1hr build time can be reduced to 20min). If you’re only building for one device, 25GB-50GB is fine. If you plan to build for several devices that do not share the same kernel source, aim for 75GB-100GB. This space will be permanently occupied on your drive, so take this into consideration.

You can also enable the optional ccache compression. While this may involve a slight performance slowdown, it increases the number of files that fit in the cache. To enable it, run:

ccache -o compression=true

Note: If compression is enabled, the ccache size can be lower (aim for approximately 20GB for one device).

Initialize the LineageOS source repository

The following branches are currently supported for building image for libvirt QEMU virtual machine:

lineage-21.0

Enter the following to initialize the repository:

Note: Make sure the branch you enter here is the one you wish to build!

cd ~/android/lineage
repo init -u https://github.com/LineageOS/android.git -b lineage-22.1 --git-lfs

Download the source code

To start the download of the source code to your computer, type the following:

repo sync

The LineageOS manifests include a sensible default configuration for repo, which we strongly suggest you use (i.e. don’t add any options to sync). For reference, our default values are -j 4 and -c. The -j 4 part implies be four simultaneous threads/connections. If you experience problems syncing, you can lower this to -j 3 or -j 2. On the other hand, -c makes repo to pull in only the current branch instead of all branches that are available on GitHub.

Note: This may take a while, depending on your internet speed. Go and have a beer/coffee/tea/nap in the meantime!

Tip: The repo sync command is used to update the latest source code from LineageOS and Google. Remember it, as you may want to do it every few days to keep your code base fresh and up-to-date. But note, if you make any changes, running repo sync may wipe them away!

Start the build

Time to start building!

Setup the environment:

source build/envsetup.sh

Virtual A/B partition scheme is used by default. If you would like to use A-only partition scheme instead (which requires less space), run the following command prior to each build:

export AB_OTA_UPDATER=false

Select the build target by running the following command, where <target> is one of the entries in the table below:

breakfast <target>

Target	Architecture	Type
virtio_arm64	ARM (32-bit + 64-bit)	PC
virtio_arm64only	ARM (64-bit only)	PC
virtio_x86_64	x86 (64-bit only)	PC
virtio_x86_64_car	x86 (64-bit only)	Automotive
virtio_x86_64_tv	x86 (64-bit only)	Android TV

Important: Running one of the x86_64 targets require a CPU which supports the SSE 4.2 instruction set, otherwise it will not boot.

Important: If you wish to run the virtual machine on ARMv9 devices (with hardware acceleration), you must select the virtio_arm64only target. The virtio_arm64 target will not boot on these processor variants, as they don’t support 32-bit mode.

Tip: For ARMv8 devices, either virtio_arm64 or virtio_arm64only would work (with hardware acceleration). The main difference is, the virtio_arm64only target does not support 32-bit only applications or tools.

Now, build the installation image:

m espimage-install

If the build completed without errors, the installation image will appear at out/target/product/<target>/lineage-*-20241220-UNOFFICIAL-<target>.img.

(Optional) Alternatively, you could also build installation image in ISO9660 format (only available for x86_64 targets):

m isoimage-install

If the build completed without errors, the installation image will appear at out/target/product/<target>/lineage-*-20241220-UNOFFICIAL-<target>.iso.

Now, transfer the installation image to the device which you wish to run it on.

Install the virtual machine software

On Debian / Ubuntu, installing the package virt-manager would install the GUI manager, and everything that required for libvirt QEMU virtual machine as well as their dependencies.

Run the following command to install it:

sudo apt install virt-manager

Additionally, install the following packages according to your build’s architecture:

Android Architecture	Packages to install
ARM (32-bit + 64-bit)	qemu-system-arm qemu-efi-aarch64
ARM (64-bit only)	qemu-system-arm qemu-efi-aarch64
x86 (64-bit only)	qemu-system-x86 ovmf

Create and configure the virtual machine using `virt-manager`

Warning: This section uses Debian 12 (bookworm) as example. The instructions for other OSes may differ.

Launch virt-manager, by opening “Virtual Machine Manager” from the Application menu, or type it on Terminal.

Virtual machine creation and common configurations

Firstly, click Edit > Preferences > General > Enable XML editing.

Now, on the menu bar, select File > New Virtual Machine. A new window named “New VM” will pop up.

Step 1

Select Manual install, expand Architecture options, and select the correct architecture for the built image, as described below:

Android Architecture	QEMU Architecture
ARM (32-bit + 64-bit)	aarch64
ARM (64-bit only)	aarch64
x86 (64-bit only)	x86_64

After selecting the correct architecture, click Forward.

Step 2

Search and select Generic Linux 2022 on Select the operation system you are installing field. Click Forward.

Step 3

Specify the number of CPU cores and the size of memory that you’re willing to allocate to the virtual machine. Minimal RAM requirement is 2048 MiB. After populating these fields, click Forward.

Step 4

Untoggle Enable storage for this virtual machine, as we will setup storage for this virtual machine later. After doing this, click Forward.

Step 5

Specify the name that you would like to assign to the virtual machine, and select the network which you wish to connect to in Network selection menu, click Forward.

Select `Chipset` or `Machine` and `Firmware`

The virtual machine configuration window will pop up.

On theOverview tab, select Chipset or Machine and Firmware type according to the architecture, as described below:

Android Architecture	Chipset / Machine	Firmware
ARM (32-bit + 64-bit)	virt (required)	Custom: /usr/share/AAVMF/AAVMF_CODE.no-secboot.fd
ARM (64-bit only)	virt (required)	Custom: /usr/share/AAVMF/AAVMF_CODE.no-secboot.fd
x86 (64-bit only)	Q35 (recommended)	UEFI x86_64: /usr/share/OVMF/OVMF_CODE_4M.fd

Click Apply.

On Memory tab, toggle Enable shared memory, click Apply.

Create virtual disks

Click Add Hardware on the bottom left corner, new window Add New Virtual Hardware will appear.
Select Storage, select Disk device on Device type menu, and select VirtIO on Bus type menu.
Fill in the disk size.
Note: Virtual A/B build (default) requires 13 GiB of size for the first disk, and A-only build requires 5 GiB of size for the first disk.
Click Finish.
Repeat the above steps, to add disk for storing userdata. Minimum size of 2 GiB is recommended.

Attach the installation image

Click Add Hardware on the bottom left corner, new window Add New Virtual Hardware will appear.
Select Storage.
If the installation image is in ISO9660 format, select CDROM device on Device type menu, and select SATA on Bus type menu; Otherwise, select Disk device on Device type menu, and select USB on Bus type menu.
Expand Advanced, toggle Readonly.
Select Select or create custom storage, select the installation image.
Click Finish.
On Boot Options tab, toggle SATA CDROM 1 or USB Disk 1, click Apply.

Configure virtual machine input

Tablet or Mouse

If the device has a touchscreen and you would like to interact with the virtual machine using a touchscreen, or if you are controlling from remote desktop, you must use tablet input device for the virtual machine.

Note: Both EvTouch and VirtIO types of tablets are supported.

Otherwise, use mouse input device.

Note: Both PS/2 and USB types of mice are supported.

Keyboard

Keyboard is always needed. Ensure there is a keyboard included in virtual machine hardware.

Note: VirtIO, PS/2 and USB types of keyboards are supported.

Configure virtual machine graphics

Video

If Video tab is missing, add it using the Add Hardware button on the bottom left corner.
On Video tab, select Virtio on Model menu, click Apply.
If the device and the remote desktop application supports 3D accelerated graphics, Toggle 3D acceleration, click Apply.

(Optional) To specify custom display resolution, first enable Edit XML switch to the XML tab, insert <resolution x="<Width>" y="<Height>"/>, like this:

 <video>
 <model type="virtio" heads="1" primary="yes">
     <acceleration accel3d="yes"/>
     <resolution x="1920" y="900"/>
 </model>
 <alias name="video0"/>
 <address type="pci" domain="0x0000" bus="0x00" slot="0x01" function="0x0"/>
 </video>

Warning: Some rare host video cards may not display 3D accelerated graphics properly. If that happens, please untoggle 3D acceleration.

Display

If Display tab is missing, add it using the Add Hardware button on the bottom left corner.
Open Display tab.
Select None on Listen type menu.
If 3D acceleration is enabled on Video tab, toggle OpenGL, and select an active host video card on the menu below of OpenGL toggle.
Click Apply.

Configure virtual machine sound

Sound card model AC97 (which is the default) is recommended. Other models might work too but may have issues.

Important: The aarch64 architecture does not have a sound card added by default. You will have to add it manually.

Create the new virtual machine

Click Begin Installation in the top left corner, the installation process will proceed, and then the virtual machine will start for the first time.

Install LineageOS to the virtual machine

The virtual machine should boot into the boot manager menu of the installation image.

Select the first option called something akin to Install LineageOS using arrow keys, and then press Enter.
The virtual machine should enter LineageOS Recovery. You could select an option using arrow keys and enter it by pressing Enter.
Select Factory reset > Format data/factory reset > Format data.
Select Apply update > Choose INSTALL > Select lineage-*-20241220-UNOFFICIAL-<target>.zip.

Congratulations! You now have installed LineageOS in the virtual machine.

You can now select Reboot system now to boot into LineageOS.

Run LineageOS inside the virtual machine

The virtual machine should enter LineageOS boot menu.

If the virtual machine is configured with 3D acceleration enabled, boot LineageOS by selecting the first option.

Otherwise, select Advanced options > LineageOS * (Kernel version *) (Swiftshader graphics).

Run Generic System Images inside the virtual machine

Here we will utilize GSIs from the Android Open Source Project website as example. There are three ways to run it:

Dynamic System Updates

Tip: This is the most convenient method.

Important: Make sure the userdata disk is not too small. Minimum size of 8 GiB is recommended.

When booted into Launcher, open Settings app.
Enable Developer options, go back to homepage, navigate to System > Developer options.
Open DSU Loader, select the DSU package that you wish to install, click Agree.
Once the installation finishes, you could reboot to the GSI by clicking Restart on Dynamic System Updates notification.

Specify GSI image as the third VirtIO disk

Download a GSI image archive (equal or higher Android version with matching architecture) from Generic System Image releases.
Extract system.img from the downloaded archive.
Add system.img as the third VirtIO disk.
Boot the virtual machine into recovery mode, perform factory reset.
Reboot to boot menu, select Advanced options > Boot GSI from /dev/block/vdc with LineageOS * (Kernel version *).

Flash GSI image to `system` logical partition

Download a GSI image archive (equal or higher Android version with matching architecture) from Generic System Image releases.
Extract system.img from the downloaded archive.
Boot the virtual machine into recovery mode, and perform a factory reset.
Enter fastbootd mode by selecting Advanced > Enter fastboot.

Delete unneeded logical partitions, and flash the GSI image, using fastboot:

 fastboot -s tcp:<IPv4 address that shown on menu header> delete-logical-partition product
 fastboot -s tcp:<IPv4 address that shown on menu header> delete-logical-partition product_a
 fastboot -s tcp:<IPv4 address that shown on menu header> delete-logical-partition product_b
 fastboot -s tcp:<IPv4 address that shown on menu header> delete-logical-partition system_ext
 fastboot -s tcp:<IPv4 address that shown on menu header> delete-logical-partition system_ext_a
 fastboot -s tcp:<IPv4 address that shown on menu header> delete-logical-partition system_ext_b
 fastboot -s tcp:<IPv4 address that shown on menu header> flash system <path to GSI system.img>

Reboot to boot menu, proceed with the first option.