Split installation

🚧	This page is a work-in-progress. Some information contained within may be inaccurate or incomplete.

WARNING: This method should work on any device without UEFI but further tests are needed. Split installation is experimental and was tested by one person on one specific device!

The standard method for installing postmarketOS to internal storage utilizes a single partition (either system or userdata) to host a combined image, which internally maps pmOS_boot and pmOS_root via loop devices. In contrast, the split method involves flashing the pmOS_boot and pmOS_root images directly and separately into the dedicated system and userdata partitions.

Instead of the standard full-image deployment, we split the components:

pmOS_boot (kernel, initramfs) is flashed into the old Android system partition.
pmOS_root (rootfs) is flashed into the larger Android userdata partition.

Prerequisites

A host machine with pmbootstrap installed.
A fully stable USB connection (ensure a high-quality standard cable is used).
Root, Fastboot, or Download mode access allowing raw partition writing.

Installation

Initialize pmbootstrap and build the installation files using the split flag, which forces the creation of separate sub-partition images instead of a single combined rootfs:
```
$ pmbootstrap init
$ pmbootstrap install --split
$ pmbootstrap export
```
Flash the kernel image to the Android native boot/kernel partition:
```
$ pmbootstrap flasher flash_kernel
```
Flash the remaining split components directly to the internal partitions using the exported images located in /tmp/postmarketOS-export/.

For generic Fastboot devices

$ fastboot flash system /tmp/postmarketOS-export/codename-boot.img
$ fastboot flash userdata /tmp/postmarketOS-export/codename-root.img

For Samsung devices (using Heimdall)

Run one of the following command pairs, depending on your device's PIT layout:

$ heimdall flash --SYSTEM /tmp/postmarketOS-export/codename-boot.img --USERDATA /tmp/postmarketOS-export/codename-root.img

or

$ heimdall flash --FACTORYFS /tmp/postmarketOS-export/codename-boot.img --DATAFS /tmp/postmarketOS-export/codename-root.img

Troubleshooting

Flashing fails / Heimdall protocol errors

Samsung's download mode protocol via Heimdall can be highly sensitive to raw image structures and partition size boundaries. If the flashing process fails or is rejected by the device, both images must be converted into Android Sparse Images before flashing:

$ img2simg /tmp/postmarketOS-export/codename-boot.img /tmp/boot-sparsed.img
$ img2simg /tmp/postmarketOS-export/codename-root.img /tmp/root-sparsed.img

After conversion, repeat the Heimdall/Fastboot flashing steps using the generated sparsed images.