Installation guide

From postmarketOS
Revision as of 19:54, 1 September 2021 by Ollieparanoid (talk | contribs) (→‎See also: link to pmb talk)
Jump to navigation Jump to search


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:

$ ls


Safety first

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  # (only if pmbootstrap was already installed!)

Then run the following in a Linux terminal:

$ pmbootstrap init

Work path

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 (50): alcatel, amazon, arrow, asus, bq, chuwi, fairphone, finepower, fly, 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, sharp, sony, surftab, t2m, tablet, teclast, tokio, 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

User interface

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 (17): 
 * none: No graphical environment
 * asteroid: (Wayland) Smartwatch UI from AsteroidOS
 * fbkeyboard: Plain framebuffer console with touchscreen keyboard support
 * glacier: (Wayland) Open-source alternative to the SailfishOS UI
 * gnome: (Wayland) Gnome Shell
 * i3wm: (X11) Tiling WM (keyboard required)
 * kodi: (Wayland) 10-foot UI useful on TV's
 * lxqt: (X11) Lightweight Qt Desktop Environment (stylus recommended)
 * mate: (X11) MATE Desktop Environment, fork of GNOME2 (stylus recommended)
 * phosh: (Wayland) Mobile UI developed for the Librem 5 (works only with numeric passwords!)
 * plasma-bigscreen: (Wayland) 10-feet variant of Plasma, made for big screen TVs
 * plasma-desktop: (X11/Wayland) KDE Desktop Environment (works well with tablets)
 * plasma-mobile: (Wayland) Mobile variant of KDE Plasma (does not run without hardware acceleration, allows only numeric passwords!)
 * shelli: Plain console with touchscreen gesture support
 * sway: (Wayland) Tiling WM, drop-in replacement for i3wm (DOES NOT RUN WITHOUT HW ACCELERATION!)
 * sxmo: (X11) Simple X Mobile: Mobile environment based on simple & suckless software (best compatibility on pinephone)
 * weston: (Wayland) Reference compositor (demo, not a phone interface)
 * xfce4: (X11) Lightweight desktop (stylus recommended)

More questions

Unless you know that you want to change something, it's fine to answer with the defaults here by just pressing the return key.

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.

Installation and flashing

Note Not all installation and flash methods work for all devices. Please check your device wiki page for further instructions! Below you will find generic explanations of what the install and flash actions do, just in case the installation instructions are missing for your device. If that is the case, please extend the device wiki accordingly.
Note When running the install process, you will be prompted for a password. If your user interface doesn't allow a full keyboard at the lock screen, or you do not have a keyboard attached to your device, you should create a numeric password.

pmbootstrap install

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 (use lsblk to figure out the correct path to your 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

If your device has a Y in the FDE column of the all devices table, you can enable full disk encryption with the --fde parameter. To format with FDE enabled and flash directly to an SD card, use:

$ pmbootstrap install --fde --sdcard=/dev/mmcblk

pmbootstrap flash

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
Note Partition names are caSE_senSitive. If flashing onto a Samsung device, use heimdall print-pit to verify.

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

See also