Pmbootstrap

pmbootstrap (git) is the central command-line application for postmarketOS development. Among other things, it allows building packages, creating installation images and flashing them to your phone. If you only want to install postmarketOS, make sure to read the installation article first since you might not need to install pmbootstrap depending on the method.

Installation
pmbootstrap runs on pretty much any Linux distribution with python3, openssl and git installed. It uses Alpine Linux chroots internally to avoid installing software on the host machine. If you don't run Linux on your PC, see.

From package manager
Use the package manager of your distribution to install pmbootstrap:

Continue reading at.

From git
Follow this section if your Linux distribution doesn't have pmbootstrap packaged, or its version of pmbootstrap is too old, or you would like to change the code. Run the following to clone and install pmbootstrap from git.

If this returns something like  instead of a version number, ensure that   is in your. For example by adding the following to your  (zsh:  ): Then open a new terminal and try again.

Continue reading at.

Other operating systems
Running pmbootstrap on other operating systems than Linux is not supported. If you run another OS, consider setting up a virtual machine with Linux. Some people also made it worth with WSL, see the Windows FAQ. But again, it's not officially supported - we recommend getting some sort of Linux install instead and running it there.

Using pmbootstrap
Frequent users may want to set up tab completion at this point, to be able to automatically complete your pmbootstrap commands and arguments with the tab key while writing them.

Initialization
Before pmbootstrap can be used, a number of configuration questions need to be answered. The sections below go into detail for the various questions.

If you already ran this before, run the following to update your local clone of pmaports.git instead:

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. pmbootstrap will automatically clone pmaports.git into a subdirectory of the work path.

Location of the 'work' path. Multiple chroots (native, device arch, device rootfs) will be created in there. Work path [/home/user/.local/var/pmbootstrap]: Setting up the native chroot and cloning the package build recipes (pmaports)... Clone git repository: https://gitlab.com/postmarketOS/pmaports.git Cloning into '/home/user/.local/var/pmbootstrap/cache_git/pmaports'... NOTE: pmaports path: /home/user/.local/var/pmbootstrap/cache_git/pmaports

Channel
Unless your device is in the community or main category of devices, you need to choose  here. Otherwise you can consider using the latest release. See the releases article for more information about the difference between the release channels.

Choose the postmarketOS release channel. Available (7): Channel [edge]:
 * edge: Rolling release / Most devices / Occasional breakage: https://postmarketos.org/edge
 * v22.12: Latest release / Recommended for best stability
 * v22.06: Old release (unsupported)
 * v21.12: Old release (unsupported)
 * v21.06: Old release (unsupported)
 * v21.03: Old release (unsupported)
 * v20.05: Old release (unsupported)

Device
Type in the vendor and code-name of your device at the prompt. If you're unsure, find your device in the list of devices.

In case you do not wish to install to a real device, you can create a VM image for a QEMU device such as qemu-amd64. Run it afterwards with, as described in the related wiki pages.

User interface
Choose the user interface you would like to install. Check your device's wiki page, it may have more information on which interfaces are known to be working with your device. Weston and XFCE4 are usable on devices which do not have hardware 3D acceleration, the others are notably slowed down. If you are unsure, read Category:Interface for information.

Available user interfaces (20): User interface [phosh]:
 * none: Bare minimum OS image for testing and manual customization. The "console" UI should be selected if a graphical UI is not desired.
 * asteroid: (Wayland) Smartwatch UI from AsteroidOS
 * console: Console environment, with no graphical/touch UI
 * fbkeyboard: Plain framebuffer console with touchscreen keyboard support
 * framebufferphone: Minimalist framebuffer menu/keyboard UI accessible via touch/volume keys & compatible scripts
 * gnome: (Wayland) Gnome Shell
 * gnome-mobile: (Wayland) Gnome Shell patched to adapt better to phones (Experimental)
 * i3wm: (X11) Tiling WM (keyboard required)
 * kodi: (GBM) 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
 * 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)
 * shelli: Plain console with touchscreen gesture support
 * sway: (Wayland) Tiling WM, drop-in replacement for i3wm (DOES NOT RUN WITHOUT HW ACCELERATION!)
 * sxmo-de-dwm: Simple Mobile: Mobile environment based on SXMO and running on dwm
 * sxmo-de-sway: Simple Mobile: Mobile environment based on SXMO and running on sway
 * 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  key.

Additional options: extra free space: 0 MB, boot partition size: 256 MB, parallel jobs: 3, ccache per arch: 5G, sudo timer: False, mirror: http://mirror.postmarketos.org/postmarketos/ 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]: Available locales (14): C.UTF-8, ch_DE.UTF-8, de_CH.UTF-8, de_DE.UTF-8, en_GB.UTF-8, en_US.UTF-8, es_ES.UTF-8, fr_FR.UTF-8, it_IT.UTF-8, nb_NO.UTF-8, nl_NL.UTF-8, pt_BR.UTF-8, ru_RU.UTF-8, sv_SE.UTF-8 Choose default locale for installation [C.UTF-8]: Device hostname (short form, e.g. 'foo') [pine64-pinephone]: After pmaports are changed, the binary packages may be outdated. If you want to install postmarketOS without changes, reply 'n' for a faster installation. Build outdated packages during 'pmbootstrap install'? (y/n) [y]: WARNING: The chroots and git repositories in the work dir do not get updated automatically. Run 'pmbootstrap status' once a day before working with pmbootstrap to make sure that everything is up-to-date. DONE!

Installing postmarketOS
Depending on the device, the installation instructions may be quite different. You might need to unlock or flash a bootloader before continuing here, or you may need to use a specific install command. Make sure you read the installation section of your device's wiki page first.

All device ports have in common that they run some form of the  command at one point. It will build a chroot with the full installation as it will be placed on the device, copy it to an image file or write it directly to an SD card and ask you for the user and encryption password. Below are the most commonly used  commands.

All examples have  added to enable Full Disk Encryption. Omit it if you don't want to encrypt your device or if your device port isn't able to show the FDE prompt yet (see FDE column of the all devices table).

Find all available arguments (such as ones for choosing different filesystems etc.) with.

SD card
Devices like the PinePhone, Samsung Galaxy S II, Nokia N900, various laptops etc. boot from an SD card, USB stick or other external storage. Find the name with  first and make sure it is the right one as you will overwrite everything on it. Use a path without partition number at the end, such as.

If your device is able to boot from SD card without flashing anything (such as the PinePhone), you should now be able to insert it into your device and boot it up. You are done with installing postmarketOS, congratulations!

To make Androids like the Samsung Galaxy S II boot from SD card, you will need to flash a boot.img file to the internal storage. Read on at.

Encrypted Image file
Most Androids, the Librem 5 and other devices need to have an image file generated, that will then be flashed to the device while it is in a special flashing mode. To generate such an image, run:

Then read on at.

Android recovery zip
A less reliable, but for some devices required method is using the Android recovery zip. The Installation from recovery mode article explains how to generate the zip file and how to flash it.

pmbootstrap flasher
This action wraps various flash programs (e.g. fastboot and heimdall) with a common syntax, and automatically fills out the paths to the files generated earlier during. Bring your phone into the flashing mode, typically by holding a special button combination such as +  while booting up. This should be described in you device's wiki page.

If you specify partition names below, note that they are case sensitive. If flashing onto a Samsung device, you can use  to verify the names.

flash_rootfs
Flash the rootfs to internal storage. You will need to do this, unless you plan to boot the rootfs from elsewhere, such as from SD card. Beware that this will overwrite the existing installation/data on your phone!

For Androids, we don't change the partition layout. If the default partition (typically "system") is too small for the generated image, it is possible to flash to another partition. 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  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  ). Using multiple partitions with LVM is planned.

flash_kernel
For Androids, you will also need to flash a boot.img (kernel + initramfs). Instruct pmbootstrap to do so with:

Afterwards you should be able to restart your phone and postmarketOS should boot up. You are done with installing postmarketOS, congratulations!

Inspecting generated files
If you want to conveniently access the files generated by, let pmbootstrap create a bunch of symlinks with.

Run the following to extract the generated initramfs:

Building packages
Build any package from pmaports.git, for example. pmbootstrap will automatically pick one of the architectures that the APKBUILD can be built for, preferably the native architecture of the PC running pmbootstrap, or if that's not possible, the device's architecture. You can explicitly specify an architecture with.

pmbootstrap uses cross compilers as described in Build_internals.

If you edited the sources of an, update its checksums:

To find out where your local  copies are saved (for instance, in order to modify them), run:

If you modify anything in there, you will need to update its checksums and then re-build as above.

To build a package from Alpine, it needs to be forked from Alpine's aports.git first:

It is also possible to specify a local source tree for building a package.

Generate a template for a new package:

Entering chroots
Enter the armv7 building chroot:

Run a command inside a chroot:

Safely delete all chroots:

Running CI scripts locally
Before a patch with modifications to pmaports (or other postmarketOS projects, such as pmbootstrap itself) gets accepted, it needs to pass the CI scripts. These run automatically when you submit the patch, but of course it makes sense to run it beforehand on your machine locally. That way you can fix up your patches until it passes and you have a shorter test iteration time than you would have with pushing it to the server every time.

Navigate to the git repository that you have modified and run the  action.

See the pmbootstrap CI article for more information on this feature.

Device porting assistance
Analyze Android boot.img files (also works with recovery OS images like TWRP):

Check kernel configs:

Edit a kernel config:

Repository maintenance
Generate cross-compiler aports based on the latest version from Alpine's aports:

Manually rebuild package index:

List pmaports that don't have a binary package:

Increase the pkgrel for each aport where the binary package has outdated dependencies (e.g. after soname bumps):

Logging
pmbootstrap writes all log output, and each shell command it runs to  inside the work dir. Use the following command to follow the log in a second terminal:

Use  on any action to get verbose logging:

Parse a single deviceinfo and return it as JSON:

Parse a single APKBUILD and return it as JSON:

Parse a package from an APKINDEX and return it as JSON:

Clean up
The  action is used to clean up files generated while using pmbootstrap:

Removing and recreating chroots is relatively fast, as the Alpine packages that get installed into the chroots are still cached. Sometimes users ask how to completely remove everything related to pmbootstrap (all caches and the config file), this would be done as follows. You can do this if your pmbootstrap install is completely broken for some reason, and then cleanly re-install it as described in this article.