If you own a device which has been ported to postmarketOS, then this page will help you to obtain, build, and install postmarketOS to this device.
Any commands that are expected to be entered into a terminal are prefixed with
$. You should not enter that character, it is merely to designate that the following commands are intended to be input/executed within a terminal. For example, the following command to list contents of the current working directory,
ls, will be mentioned on this page as:
- We assume that you are using Linux. If you don't have Linux installed, please set up a virtual machine with VirtualBox first. Windows subsystem for Linux (WSL) does not work!
- The host operating system needs to run Linux 3.17 or newer (first kernel with getrandom syscall)
- A few gigabytes of free space
Beware that by following these instructions, you will overwrite everything that is currently on your device. You will lose all data and it might not be possible to restore the original operating system. There is a risk of hard-bricking your device, meaning it may be impossible to recover without specialist tools.
Fortunately, most Android-based devices are fairly foolproof; even if your flashed images don't boot, you can still access the flashing mode and fix the mistakes. For details, have a look at your device-specific wiki page.
TL;DR: do your research, don't have important data on your device.
Install pmbootstrap, our lightweight postmarketOS development and installation tool. If you already had pmbootstrap installed make sure that it is updated to the latest version and update your files, to get the newest patches:
$ pmbootstrap pull
Then run the following in a Linux terminal:
$ pmbootstrap init
Make sure that the location has a few GB of space available, and that it is a relatively standard Linux filesystem (one that supports device nodes and symbolic links). Notably unsupported are: eCryptFS, encfs, fat, ntfs, nfs shares, tmpvs, and VirtualBox shared folders.
Location of the 'work' path. Multiple chroots (native, device arch, device rootfs) will be created in there. Work path [/home/user/.local/var/pmbootstrap]:
Type in the vendor and code-name of your device as listed here, and optionally a custom username.
Choose your target device vendor (either an existing one, or a new one for porting). Available vendors (45): amazon, asus, bq, chuwi, fairphone, finepower, fujitsu, google, gp, hisense, htc, huawei, infocus, jolla, leeco, lenovo, lg, medion, meizu, motorola, nextbit, nobby, nokia, oneplus, oppo, ouya, pine64, planet, purism, qemu, raspberry, samsung, semc, sony, surftab, t2m, tablet, teclast, wiko, wileyfox, wingtech, xiaomi, yu, zte, zuk
Vendor [nokia]: samsung Available codenames (43): a3ulte, a5ulte, a5y17lte, apexq, ariesve, espresso10, expressatt, golden, gt510wifi, gts210velte, gts210vewifi, hero2lte, herolte, i747m, i8200, i9003, i9070, i9100, i9195, i927, i9305, j1mini3g, j3nxlte, jflte, klte, kminilte, kylepro, kylessopen, kylevess, lt01wifi, lt023g, maguro, manta, matissewifi, n5110, n7100, nevisp, p4wifi, royss, s6500d, serranodsdd, serranovelte, zanin
Carefully choose the user interface you would like to install. Check your device's wiki page for interfaces that are known to be working with your device. Weston and XFCE4 are usable on devices which do not have hardware 3D acceleration (most of them!), the others are notably slowed down. Please read the corresponding user interface article for information about how usable each interface is and keep in mind that most of them are not that usable yet.
Available user interfaces (11): * none: No graphical environment * hildon: (X11) Lightweight GTK+2 UI (optimized for single-touch touchscreens) (DISABLED FOR ARMHF, ARMV7!) * i3wm: (X11) Tiling WM (keyboard required) * kodi: (Wayland) 10-foot UI useful on TV's * mate: (X11) MATE Desktop Environment, fork of GNOME2 (stylus recommended) * phosh: (Wayland) Mobile UI developed for the Librem 5 * plasma-mobile: (Wayland) Mobile variant of KDE Plasma, optimized for touchscreen (slow without hardware acceleration!) * plasma-mobile-extras: Plasma Mobile with more apps pre-installed (video and music players, pdf reader, etc.) * shelli: Plain console with touchscreen gesture support * sway: (Wayland) Tiling WM, drop-in replacement for i3wm (DOES NOT RUN WITHOUT HW ACCELERATION!) * weston: (Wayland) Reference compositor (demo, not a phone interface) * xfce4: (X11) Lightweight GTK+2 desktop (stylus recommended) User interface [weston]:
Unless you know that you want to change something, it's fine to anwer with the defaults here by just pressing the
Build options: Parallel jobs: 3, ccache per arch: 5G Change them? (y/n) [n]: Additional packages that will be installed to rootfs. Specify them in a comma separated list (e.g.: vim,file) or "none" Extra packages [none]: Your host timezone: Europe/Berlin Use this timezone instead of GMT? (y/n) [y]: Device hostname (short form, e.g. 'foo') [samsung-kylessopen]: Would you like to copy your SSH public keys to the device? (y/n) [n]: WARNING: The applications in the chroots do not get updated automatically. Run 'pmbootstrap zap' to delete all chroots once a day before working with pmbootstrap! It only takes a few seconds, and all packages are cached. Done!
Installation and flashing
The install action essentially does the following:
- Build a chroot with the full installation as it will be placed on the device
- Copy that to an encrypted system image file
- Ask you for the user and encryption passwords
Furthermore you can change the output type (system image) to something else with the following parameters.
--sdcard: Format and copy everything to an SD card
--android-recovery-zip: Create a zip file, that can be used with TWRP, CWM or other Android recovery systems (detailed instructions)
Example commands (only using one at a time makes sense):
$ pmbootstrap install $ pmbootstrap install --sdcard=/dev/mmcblk $ pmbootstrap install --android-recovery-zip $ pmbootstrap install --fde $ pmbootstrap install --help
It is possible to enable full disk encryption (FDE) with the
--fde parameter, but it is experimental, and might not work at this point. (if, for example, the FDE interface osk-sdl has not been ported to your device yet).
This command wraps various flash programs (e.g. fastboot and heimdall) with a common syntax, and automatically fills out the paths to the generated files. Usually you need to flash the system image (unless you did the SD card or recovery zip installation):
$ pmbootstrap flasher flash_rootfs
In case your system partition is too small for the generated image (e.g. because you chose Plasma Mobile as your UI), it is possible to flash to another partition as well. Just be sure to erase any previous installations of postmarketOS in other partitions, because the init script will start with the first one that it encounters. (To delete a previous version either use
fastboot format system for fastboot compatible devices, or simply install the known working OS, e.g. Android, on it. And if you really know what you are doing, you might consider using
dd). Using multiple partitions with LVM is planned (pmbootstrap#60).
$ pmbootstrap flasher flash_rootfs --partition userdata
And then you need to boot or flash the kernel (so run only one of the commands). Again, this is not necessary when you have used the recovery zip. But it is necessary in most cases with the SD card (unless the device can boot the kernel from the SD card like the N900). To boot from SD, with the device in fastboot mode (with device off, press Power + Volume Down until it enters fastboot mode), type the first line into your computer:
$ pmbootstrap flasher boot $ pmbootstrap flasher flash_kernel
As with all
pmbootstrap commands, you can check the help pages for details:
$ pmbootstrap flasher --help $ pmbootstrap flasher flash_rootfs --help