Run pmbootstrap install
without any parameters:
$ pmbootstrap install
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.
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. |
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.
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.
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
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:
~/.local/var/pmbootstrap
) is fine, but you can optionally move it e.g. to an external drive if more space is needed.edge
for the edge branch, and v25.06
for the latest stable release.downstream
category (using downstream kernels) are only available in the edge
branch. You can find the category your device belongs to on its wiki page.vendor-codename
format.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
.
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:
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.
Once pmbootstrap has been succesfully initialized, we can proceed with generating the image, which involves the pmbootstrap install
command. This command does three things:
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.Choose one of the following depending on your usecase.
Run pmbootstrap install
without any parameters:
$ pmbootstrap install
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...
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
--disk
(see "Installing to SD card or USB drive").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).
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
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. |
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!
You can gather more ideas by checking out the Dogfooding category.
Some solutions to common problems are described in this section; for more specific troubleshooting steps, see the Troubleshooting article.
pmbootstrap status
and make sure everything is up-to-date. If not, run pmbootstrap pull
to update the local clone of the pmaports repository.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.pmbootstrap zap
(answer "y" to all questions).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
.
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
.
pmbootstrap export
and flash the generated files manually, using the flash tool of your choice, or;You might see an error like "ERROR: BOOT partition is too small for given file. Use --skip-size-check to flash anyways.
". The most common cause for this is that the combined initramfs and kernel image is too large.
See pmbootstrap/Troubleshooting#Generated boot/kernel image too large for boot partition for information on how to fix this.