How to build LineageOS inside a container

6 min read

LineageOS is a free and open-source Android distribution. To port LineageOS to a new device, to add a kernel module such as WireGuard, or to make your own version, you need to setup a build environment.

Android is composed of a multitude of software, with a build process tested on Ubuntu. If you do not use Ubuntu as your main distribution, you can still build Android inside a container. systemd-nspawn is a container runtime shipped with systemd. This tutorial explains how to setup a LineageOS build environment in a systemd-nspawn container.

I encourage you to consult the LineageOS wiki alongside this article. The references to the wiki point to the Google Pixel XL pages, code name marlin, but the instructions for all the devices are based on a common template.


Building Android requires a decent machine and network connection:

  • RAM: at least 8 GB (along with some swap space).
  • Storage: around 200 GiB (including the source code, cache, and output files).
  • Network: approximately 30 GB of data for the initial download.

The last resource you need is a lot of time. The first download and build are unbearably long (as in hours, or even days with a slow network connection). Subsequent builds are much quicker.

Setup the build environment

The LineageOS developers recommend Ubuntu 20.04 LTS (Focal Fossa). The system is installed inside a systemd-nspawn container. The purpose is to keep a clean build environment, separate from your main system, while avoiding the overhead associated with virtual machines.

Install Ubuntu

You need debootstrap to install the base system, and optionally the Ubuntu archive keyring so it can verify package signatures. On Arch Linux, they can be installed with the following command:

# pacman -Sy debootstrap ubuntu-keyring

Then, you can bootstrap the base system in /var/lib/machines/ubuntu (but you can choose any other directory for this tutorial):

# debootstrap focal /var/lib/machines/ubuntu

Once installed, you can start the machine:

# systemd-nspawn -D /var/lib/machines/ubuntu

Use the --bind option to mount the cache and build directories from another location on the host:

# systemd-nspawn -D /var/lib/machines/ubuntu   \
	--bind=/storage/android:/home/user/android \

This is useful if you have a secondary hard drive with more available space.

Install the build dependencies

debootstrap only adds the main Ubuntu repository. To get access to all the required packages, you need to add the focal-updates and focal-security repositories and the universe branch to APT's sources.list configuration file:

ubuntu:~# cat /etc/apt/sources.list
deb focal main universe
deb focal-security main universe
deb focal-updates main universe

You can now run the upgrade procedure:

ubuntu:~# apt update
ubuntu:~# apt full-upgrade

Finally, install the LineageOS build dependencies:

ubuntu:~# apt install bc bison build-essential ccache curl flex g++-multilib gcc-multilib git gnupg gperf imagemagick lib32ncurses5-dev lib32readline-dev lib32z1-dev liblz4-tool libncurses5 libncurses5-dev libsdl1.2-dev libssl-dev libxml2 libxml2-utils lzop pngcrush rsync schedtool squashfs-tools xsltproc zip zlib1g-dev python-is-python3

Add an unprivileged user

Since building things as root is not recommanded, create an unpriviliedged user:

ubuntu:~# adduser --disabled-password user

No need to set any password since you can log into this account from root:

ubuntu:~# su - user

Install ccache

ccache helps to speed up the build time thanks to a cache. Start by increasing its maximum size to 50 GB:

ubuntu:~$ ccache -M 50G
Set cache size limit to 50.0 GB

Then, set USE_CCACHE=1 in ~/.bashrc:

ubuntu:~$ echo 'export USE_CCACHE=1' >> ~/.bashrc

Download the LineageOS source files

repo downloads and manages the hundreds git repositories required to build LineageOS.

Install repo

Create the directory for the user's local binaries:

ubuntu:~$ mkdir -p ~/.local/bin/
ubuntu:~$ source ~/.profile  # to include ~/.local/bin/ in PATH

Download repo and make it executable:

ubuntu:~$ curl > ~/.local/bin/repo
ubuntu:~$ chmod a+x ~/.local/bin/repo

To use repo, you need to set a git name and email:

ubuntu:~$ git config --global user@localhost
ubuntu:~$ git config --global user

Fetch the source code

Create the source directory:

ubuntu:~$ mkdir -p ~/android/lineage/
ubuntu:~$ cd ~/android/lineage/

Next, initialize the repository (specify a valid branch for your device, e.g., lineage-17.1):

ubuntu:~/android/lineage$ repo init -u -b lineage-17.1

Finally, you can download the source files (this may take a while):

ubuntu:~/android/lineage$ repo sync --force-sync

repo automatically fetches its latest version, so you can replace the previous binary with a symlink to it:

ubuntu:~$ ln -sf ~/android/lineage/.repo/repo/repo ~/.local/bin/repo

Download the device-specific source files

The first step is to source the build environment, which includes the main commands for the build process (such as breakfast and brunch):

ubuntu:~/android/lineage$ . ./build/

You can now download the device-specific source files, including the kernel (replace marlin with your device code name):

ubuntu:~/android/lineage$ breakfast marlin

If you encounter an error, continue to the next section to extract the proprietary blobs. Then, you should be able to run breakfast again without errors.

Extract the proprietary blobs

If you already have LineageOS installed on your device, you can extract the blobs from it. Install the Android platform tools, connect the device to your computer through ADB, and run the following command (replace google/marlin with the device path):

$ ~/android/lineage/device/google/marlin/

If you do not have LineageOS installed on your device, then you will have to follow the instructions for extracting proprietary binary blobs from the installation zip.

Build the system image

If you encountered an error the first time you ran breakfast, run it again:

ubuntu:~/android/lineage$ breakfast marlin

With the minimum system requirements of 8 GB of RAM + 8 GB of SWAP, the build process may stay stuck for hours on some Metalava documentation targets until it finally runs out of heap memory:

FAILED: out/soong/.intermediates/frameworks/base/api-stubs-docs/android_common/api-stubs-docs-stubs.srcjar...
Exception in thread "main" java.lang.OutOfMemoryError: Java heap space

The solution is to increase the Java heap size and to build the offending targets sequentially:

$ _JAVA_OPTIONS=-Xmx6114m mka -j1 api-stubs-docs hiddenapi-lists-docs system-api-stubs-docs test-api-stubs-docs

Then you can continue with brunch.

Close uneeded application to free up some RAM and start the build (this may take a while):

ubuntu:~/android/lineage$ brunch marlin

If you encounter an error with resize2fs not being able to open /etc/mtab, create the following symlink before restarting the build:

$ ln -s /proc/mounts /etc/mtab

If the build succeeded, you can head to the output directory:

ubuntu:~/android/lineage$ cd "$OUT"

You will find the following files:

  • boot.img: the boot image (kernel, ramdisk).
  • lineage-17.1-202XXXXX-UNOFFICIAL-<DEVICE>.zip: the system installation package.