Installing Halium-based builds

With the necessary compontents built, you are now ready to install them on your device and check whether they function as intended. There are only minor differences between Halium versions when it comes to the installation process. In all cases, the system image and rootfs are installed together on the userdata partition of the device. This is done for practical reasons, as it makes the installation process simpler to manage during the first phases of the porting process. Once the port reaches the level of maturity required for it to be offered through the UBports installer (see Finalizing the port), this must be changed in order to reserve a maximum of possible space for userdata.

In brief:

  • Halium-7.1 requires installing the boot image and system image you have built, together with the UBports rootfs, which you need to download.

  • Halium-9.0 and newer require installing the boot image you have built together with the GSI and the UBports rootfs. Both the GSI and the rootfs are available for download. Note: If you chose to build your own system.img, then you must use this instead of the GSI when installing.

In order to install Ubuntu Touch, you need a recovery image with Busybox, such as TWRP, installed on your phone. If you have not done so yet, refer to section Установка TWRP recovery and install it now.

You will also need to ensure the /data partition is formatted with ext4 and is not encrypted. Boot into recovery, check and adjust as necessary.

Flashing halium-boot.img

To install halium-boot, reboot your phone into fastboot mode. Then do the following from the root of your BUILDDIR:

fastboot flash boot halium-boot.img

Если возникли проблемы с доступом к устройству в режиме быстрой загрузки (fastboot), но к нему есть доступ к нему в режиме TWRP recovery с помощью adb, загрузитесь в этом режиме и попробуйте альтернативный способ:

adb push halium-boot.img /tmp/

On your device, choose Install in the TWRP menu, navigate to the /tmp directory, choose Image, select your image file, select Boot and swipe to flash.


Устройства Samsung: перепрошивка halium-boot.img на устройствах Samsung выполняется с помощью утилит Heimdall (в Linux) или Odin (в Windows) после первого перевода устройства в режим „download mode“. Смотрите дополнительную информацию об этих утилитах здесь. Следуйте инструкциям для выбранной утилиты, включая специальную команду для прошивки загрузочного раздела. Установите system.img и rootfs (см. ниже) на устройство в режиме recovery.

Installing system image and rootfs

Read carefully and perform only the steps which apply to your Halium version and the files you will be flashing!

Download the appropriate rootfs

Start by downloading the appropriate rootfs for your device. You need a rootfs corresponding to your device’s architecture and the Halium version you have built. At the moment there are two available versions for Halium 7.1, an armhf (32 bit) version and an arm64 (64 bit) version. For Halium 9.0 there is only an arm64 rootfs available. Follow the appropriate link below to download the one you need.

Halium-9.0: Download the GSI

(If you have built your own system.img, skip to the next step.)

Download the Halium 9 LXC container image (GSI).

Extract the downloaded file and locate the file android-rootfs.img in the directory system/var/lib/lxc/android. This is the GSI file you will be transferring to the device.

Download the halium-install script

Clone or download the halium-install repository. This repository contains tools that can be used to install a Halium system image and distribution rootfs. Reboot your device to recovery (e.g. TWRP), to get adb access again. Now use the halium-install script to install Ubuntu Touch on your device.

Perform the installation

For Halium 7.1 ports use the following command:

path/to/halium-install -p ut path/to/rootfs.tar.gz path/to/system.img

For Halium 9.0 ports, use this command:

path/to/halium-install -p ut -s path/to/ubuntu-touch-android9-arm64.tar.gz path/to/[SYSTEM_IMAGE]

where [SYSTEM_IMAGE] will be the file android-rootfs.img you downloaded and extracted, or alternatively the file system.img you built yourself.

Скрипт скопирует все необходимые файлы на устройство, а затем попросит установить на телефон пароль (по умолчанию, пароль phablet ).


halium-install might fail due to unconfigured bintfmt-support for qemu throwing errors such as „chroot: failed to run command ‘passwd’: Exec format error“. To fix this, /proc/sys/fs/binfmt_misc/register should be updated. binfmt-manager by @mikkeloscar can provide quickfix.