Installation/Using pmbootstrap

< Installation‎

This page describes the process of installing postmarketOS using pmbootstrap, the postmarketOS build tool. It provides a general outline of the installation steps - for a more detailed explanation, see the pmbootstrap article.

Preparation

If you encounter any issues during the installation process, or if you have any questions, feel free to ask for help in our Matrix/IRC chat.

You might want to read the entire article first to get a good idea of the installation process.

Check if your work drive has at least 10GB of free space. (In case you want to use an external drive, pmbootstrap will let you set the exact location later.)
Make sure to read your device's wiki page - you can find it on the Devices page or by searching the wiki.
- Keep it handy during the install process - we will be using information from it soon.
Ensure that your device is sufficiently charged, to avoid it shutting down during the flashing process.
Check if your bootloader is unlocked.
Make sure all important data on the device is backed up - see Backing up a non-pmOS phone.
- Besides backing up the userdata partition, it's also worth it to have a backup of the stock system (or another working ROM) in case you'd like to revert to your previous OS.

To run pmbootstrap, you need to be running Linux. Other operating systems are not supported - while some people have succeeded at using WSL (see Windows FAQ), your best option is to set up a Linux install or virtual machine.

Quick glossary

Boot partition - this refers to the /boot partition on Android devices, which contains the kernel and initramfs.
initramfs - the initial environment loaded into RAM by the kernel. This is what mounts the partitions and prepares the system to boot, before switching to the rootfs.
rootfs - the main system partition of postmarketOS. This is what contains all of the system and user data.

About pmbootstrap

pmbootstrap is the postmarketOS build tool. It is used for everything from building individual packages to entire images, and has various utilities which help with the porting and installation process.

It works by creating small self-contained installations (chroots) of Alpine Linux and managing all build dependencies within them. This way, you don't need to install anything manually on your host system to build images and packages; just run a few commands, and pmbootstrap will take care of everything for you.

Installing pmbootstrap

Your distro may already have pmbootstrap available in its repositories. If it doesn't, or the packaged version is too old, you can also install pmbootstrap from git.

If you've already installed pmbootstrap before, run this command to update the local clone of the pmaports repository:

$ pmbootstrap pull

Initializing pmbootstrap

For a more detailed, step-by-step guide through the initialization process, see pmbootstrap#Initialization.

Before we can begin installing postmarketOS, we need to tell pmbootstrap what device we're using and set up some basic options. To do this, run:

$ pmbootstrap init

You will be asked to answer some questions to get your environment set up, including:

Where to place the work path - this is where pmbootstrap will download files and set up chroots.
- For most users, the default suggested location (~/.local/var/pmbootstrap) is fine, but you can optionally move it e.g. to an external drive if more space is needed.
- Note that only standard Linux filesystems like ext4 are supported - NTFS, VirtualBox shared folders and various exotic filesystems will not work. You should also have about ~10GB of free space.
The release channel to use - if you're unsure, see Installation#Choosing a release channel.
- You'll be shown a list of releases to choose from; choose edge for the edge branch, and v24.06 for the latest stable release.
The vendor (manufacturer) and codename of your device - these are listed on your device's wiki page.
- The codename in the table and the wiki page title follows the vendor-codename format.
- Some devices are supported as part of "generic ports", meaning that a single port supports multiple similar devices. In some of those cases, you may need to choose the vendor and codename for the generic port instead - check the instructions on your device page if you can't find it in the device list for your vendor.
- For some devices, you may be asked additional questions related to the configuration of specific features. In most cases, the defaults are fine.
The user interface to install - note that only interfaces supported by your device will be displayed. If you're unsure, see Category:Interface for a visual guide and links to individual interfaces' wiki pages.
The username and hostname to use on the device. (You'll be asked for the password later, during image generation.)
The timezone and locale (language) to use on the device.
...and a few other questions related to the build environment.

For most questions, the suggested defaults are fine. The text between square brackets in the prompts shows the default option; pressing Enter/Return without typing anything will select it. For example:

Location of the 'work' path. Multiple chroots (native, device arch, device rootfs) will be created in there.
Work path [/home/user/.local/var/pmbootstrap]:

Pressing Enter here will set the work path to the suggested value of /home/user/.local/var/pmbootstrap.

Choosing the rootfs destination

Before we can flash postmarketOS, we must first decide where to install it.

In the case of Android devices, the standard Android OS is split into "system" and "data" partitions (newer devices may have a "super" partition instead of "system", and/or use A/B slots). The system partition is smaller (about 1-2GB, depending on the age of your device), but installing to it allows the user to quickly revert back to the original Android OS without losing data.

However, some user interfaces require more storage, and you will quickly run out of space when installing new software or adding new files. Thus, the most common options for installation destinations are:

The userdata partition - this is the partition used by Android to store user data. If you install to this partition, your Android data will be reset!
The SD card - on devices with an external storage slot, it is possible to flash the postmarketOS system image onto an SD card.

Since pmbootstrap 2.0.0, the default rootfs partition (at least on devices with fastboot) is set to userdata.

Depending on which rootfs destination you choose, the installation and flashing process will be a bit different.

Generating the image

Once pmbootstrap has been succesfully initialized, we can proceed with generating the image, which involves the pmbootstrap install command. This command does three things:

Builds a chroot with the full postmarketOS installation, as it will be installed onto the device
Asks for the user and disk encryption (if enabled) password
Generates an image file that will later be flashed, and for SD card installations -- flashes the generated image to the specified SD card.

Depending on how you want to install postmarketOS, you may also want to append the following flags to the above command:

--fde: enables Full disk encryption (FDE). (Make sure your device supports it first - there's an "FDE" column in the status table of your device's page.)
--sdcard=/dev/mmcblk...: automatically flashes the generated image to the provided block device.
--android-recovery-zip: generates an Android recovery ZIP. This is generally not recommended, and should only be used if other flashing methods do not work. See Installation from recovery mode for more information.

Usage examples

Choose one of the following depending on your usecase.

Generating a regular image

Run pmbootstrap install without any parameters:

$ pmbootstrap install

Then continue to the #Flashing section.

Installing to the SD card or USB storage

WARNING: This will overwrite all data on the SD card! Make sure any important data is backed up, and double-check that you have the correct device selected.

This works for any block device, including SD cards and USB drives. We will assume that an SD card is used, but these commands will work for any install target.

First, find the path to your device using lsblk. SD cards will usually begin with /dev/mmcblk. If you're unsure, run sudo fdisk -l /dev/[yourdevice] - this should print information about the device, including the model, which should be enough to tell whether it's the device you're looking for.

You'll need the path without the partition number at the end (for example, /dev/mmcblk0, not /dev/mmcblk0p1).

Then, run the following command (replace /dev/mmcblk... with the path you got in the previous step):

$ pmbootstrap install --disk=/dev/mmcblk...

Continue to the #Flashing the kernel section.

Enabling full disk encryption (FDE)

Full disk encryption allows you to encrypt the files on your device. Before you enable it, make sure your device supports it - there's an "FDE" column in the status table of your device's page.

To enable it, add the --fde parameter to the pmbootstrap install command:

$ pmbootstrap install --fde

You can also combine it with the other flags, such as --disk.

Flashing

WARNING: This is your last chance to make sure all important data has been backed up from the device!

Once the image has been generated, the final step is to flash it to the device. This is handled by the pmbootstrap flasher command, which automatically uses the correct flashing tool for your device.

At this point, read the Installation section in your device's wiki page. The wiki page for your device might contain additional information or prerequisites for flashing (for example, some devices will require you to flash a secondary bootloader like lk2nd before flashing the other images).

Flashing the rootfs

If you chose an SD card/USB install, and used the --disk flag, you can skip this step; this is only used to flash the rootfs to the device. Proceed to #Flashing the kernel.

Boot your device into its dedicated download/flashing mode; the exact steps differ depending on the device, but usually involve holding down a button combination while booting up the phone, or running adb reboot bootloader. Check your device's wiki page for instructions.

Then, run the following command:

$ pmbootstrap flasher flash_rootfs

To specify the partition to flash the rootfs to, use the --partition parameter:

$ pmbootstrap flasher flash_rootfs --partition=userdata

Flashing the kernel

Boot your device into its dedicated download/flashing mode; check your device's wiki page for instructions.

Then, run the following command:

$ pmbootstrap flasher flash_kernel

If your device uses fastboot, to reboot your device after flashing, run pmbootstrap chroot fastboot reboot. Using this command, rather than manually shutting down your device, ensures that writing finishes correctly.

Finishing up

Once you've flashed all of the relevant images, reboot the device. If you did everything correctly, you should be presented with the login screen of your interface of choice. Use the credentials you set up during the installation step to log in.

If all goes correctly, you should now be running postmarketOS! Enjoy!

What to do with your newly-flashed device

Find apps to install by looking at the Applications by category page
Take a picture of your setup on social media and share it with our community!

You can gather more ideas by checking out the Dogfooding category.

Troubleshooting

Some solutions to common problems are described in this section; for more specific troubleshooting steps, see the Troubleshooting article.

General troubleshooting steps

Run pmbootstrap status and make sure everything is up-to-date. If not, run pmbootstrap pull to update the local clone of the pmaports repository.
Check pmbootstrap log (you may need to open the log file if it cuts off too early). This way, you will be able to see the exact errors you're encountering.
If all else fails, try running pmbootstrap zap (answer "y" to all questions).

Newer version in binary package repositories than in aports folder

If you have used pmbootstrap before, you may encounter a warning like Package 'package' in your aports folder has version X, but the binary package repositories already have version Y. Y will be used when installing package.

Unless you have modified something in the packages, this message is generally harmless, as the latest package will be pulled anyways. In most cases, you can fix it by running pmbootstrap pull, which will update the local copy of the pmaports repository; sometimes, you may also need to run pmbootstrap zap -m.

"ERROR: Could not find dependency..." or "ERROR: Could not find aport..."

This error may sometimes happen on the "edge" branch, usually when some large package was bumped and its dependencies are still getting rebuilt, or when cross-compilation package versions become out of sync. Usually this will be resolved after a while, so wait a day or two and try again.

In case the issue persists, try running pmbootstrap zap -hc.

Flasher is stuck on "waiting for device", does not see any devices or reports "permission denied" errors

Make sure your device is booted into its dedicated fastboot/download mode.
Try a different cable.
If the issue persists, you may need to install udev rules that will allow you to access USB devices as a regular user - see Troubleshooting#flasher (fastboot) is stuck in < waiting for any device >.
If flashing still doesn't work, you can either:
- Export the image using pmbootstrap export and flash the generated files manually, using the flash tool of your choice, or;
- Try Installation from recovery mode.