Installation guide
This page describes the generic steps for installing postmarketOS using pmbootstrap, a special deploy and development tool. pmbootstrap installation is very flexible as it gives the user many choices, however other options are available for select devices: You can find pre-built images and on-device installers on the download page of postmarketOS website.
Contents
Introduction
If you own a device which postmarketOS has been ported to, this page will help you to obtain, build, and install postmarketOS to this device.
![]() |
If your device is in the Community or Main category, you can download prebuilt images on the download page. |
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
Requirements
- We assume that you are using Linux. If you don't have Linux installed, please set up a virtual machine with VirtualBox first. Or you can use Windows subsystem for Linux (WSL) (You will need this USB setup guide).
- The host operating system needs to run Linux 3.17 or newer (first kernel with getrandom syscall)
- A few gigabytes of free space
- Some devices will come with a locked bootloader, in such cases you will need to unlock it before proceeding. Check the device-specific wiki page for more details.
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.
Initialization
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
Make sure that when you are asked for the username, you specify something different from root as this will cause issues and make you unable to log in.
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]:
Device
Type in the vendor and code-name of your device at the prompt. If you're unsure, find your device in the list here.
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 * gnome-mobile: (Wayland) Gnome Shell patched to adapt better to phones (Experimental) * 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. Done!
Installation and flashing
![]() |
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. |
![]() |
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 (uselsblk
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
![]() |
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