How to Install postmarketOS on the PinePhone

postmarketOS is one of the coolest OSes for the PinePhone in my opinion because of how customizable it is during installation. It comes with barely any apps preinstalled, and it you can use whatever GUI you want on it. However, because it's so customizable, it is a huge pain to install. So hopefully this guide will help you install it.

Pre-installation

Installing postmarketOS is a lot more difficult than installing other OSes to the PinePhone. You are going to need a Linux system with atleast kernel 3.17 or newer. The Windows Subsystem for Linux will not work. So if you are using Windows, I recommend creating a USB with Ubuntu on it, and doing this process from that.

The first thing we need to do is install pmbootstrap. If you are on Alpine Linux or postmarketOS, than you can install it with sudo apk add pmbootstrap. If you are on Arch and you are fine using the AUR install the pmbootstrap package with your favorite AUR helper.

If you are not on Alpine Linux, or you don't want to use the AUR, than we will install it using pip. Install pip, and git. pip is a package manager for python that allows you to install python modules and programs. git is a version control system that pmbootstrap needs to download files it needs.

# Debian / Ubuntu / Linux Mint
sudo apt install python3-pip git

# Arch / Manjaro
sudo pacman -S python-pip git

# Fedora / Red Hat
sudo dnf install python-pip git

# openSUSE
sudo zypper in python3-pip git

Now that pip is installed, we need to use pip to install pmbootstrap.

sudo pip3 install pmbootstrap

Now that pmbootstrap is installed, we can start the postmarketOS installation process using pmbootstrap init but if you have installed postmarketOS before, make sure to run pmbootstrap pull in order to pull the latest patches.

Configuring pmbootstrap

Once you run pmbootstrap init, it should ask you for a work path. If you press enter, it will use the default work path. Otherwise, enter the work path you want to use. Once you select a work path, it should git clone pmaports to your work path.

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

Now it will ask you for a release channel. It will give you the choice for either edge or stable. At the time of writing this, stable doesn't support the PinePhone, so make sure to pick "edge".

[10:42:19] Choose the postmarketOS release channel.
[10:42:19] Available (2):
[10:42:19] * edge: Rolling release channel
[10:42:19] * stable: Stable release channel (first beta v20.05, does not have many devices yet)
[10:42:19] Channel [edge]: edge

Now it's going to ask you for your vendor. Type "pine64" and press enter.

[10:47:46] Choose your target device vendor (either an existing one, or a new one for porting).
[10:47:46] Available vendors (49): alcatel, amazon, 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
[10:47:46] Vendor [qemu]: pine64

Next it will ask you to enter your device. Type "pinephone" and press enter.

[10:47:46] Vendor [qemu]: pine64
[10:50:15] Available codenames (6): a64lts, dontbeevil, pinebookpro, pinephone, pinetab, rockpro64
[10:50:15] Device codename: pinephone

Then it will ask you to enable a proprietary component for Wifi and Bluetooth. I highly recommend enabling it, otherwise you won't get support for Wifi or Bluetooth. To enable it, type "y" and press enter.

[10:50:39] This device has proprietary components, which trade some of your freedom with making more peripherals work.
[10:50:39] We would like to offer full functionality without hurting your freedom, but this is currently not possible for your device.
[10:50:39] device-pine64-pinephone-nonfree-firmware: Wifi and Bluetooth firmware
[10:50:39] Enable this package? (y/n) [y]: y

Now enter your username of choice and press enter.

[10:55:54] Username [user]: pizzalovingnerd

And then select your UI of choice.

[10:55:59] Available user interfaces (13): 
[10:55:59] * none: No graphical environment
[10:55:59] * fbkeyboard: Plain framebuffer console with touchscreen keyboard support
[10:55:59] * gnome: (Wayland) Gnome Shell (not for armhf)
[10:55:59] * i3wm: (X11) Tiling WM (keyboard required)
[10:55:59] * kodi: (Wayland) 10-foot UI useful on TV's
[10:55:59] * mate: (X11) MATE Desktop Environment, fork of GNOME2 (stylus recommended)
[10:55:59] * phosh: (Wayland) Mobile UI developed for the Librem 5 (works only with numeric passwords!)
[10:55:59] * plasma-desktop: (X11/Wayland) KDE Desktop Environment (works well with tablets)
[10:55:59] * plasma-mobile: (Wayland) Mobile variant of KDE Plasma (slow without hardware acceleration, allows only numeric passwords!)
[10:55:59] * plasma-mobile-extras: Plasma Mobile with more apps pre-installed (video and music players, pdf reader, etc.)
[10:55:59] * shelli: Plain console with touchscreen gesture support
[10:55:59] * sway: (Wayland) Tiling WM, drop-in replacement for i3wm (DOES NOT RUN WITHOUT HW ACCELERATION!)
[10:55:59] * weston: (Wayland) Reference compositor (demo, not a phone interface)
[10:55:59] * xfce4: (X11) Lightweight GTK+2 desktop (stylus recommended)
[10:55:59] User interface [weston]: phosh

If you don't know what UI you want, I recommend picking Phosh. In the future I plan on writing a series of articles going over each UI, so that you know which one to get.

After that it will ask you for some build actions, I usually just press enter to use the default.

[10:57:55] Build options: Parallel jobs: 5, ccache per arch: 5G
[10:57:55] Change them? (y/n) [n]: 

Now it will ask you if you want any extra packages, here, you can just press enter for no extra packages, or type "none".

[10:58:39] Additional packages that will be installed to rootfs. Specify them in a comma separated list (e.g.: vim,file) or "none"
[10:58:39] Extra packages [none]: 

Now it's going to try and auto detect your timezone. If it detects it right, just type y and press enter.

[10:58:48] Your host timezone: America/Los_Angeles
[10:58:48] Use this timezone instead of GMT? (y/n) [y]: y

And finally, we need to select a hostname for postmarketOS. If you don't know what to set the hostname to, I recommend setting it to either "pinephone" or "pine64-pinephone".

[11:01:28] Device hostname (short form, e.g. 'foo') [pine64-pinephone]: pinephone

Now we are done configuring pmbootstrap.

Finding your SD Card.

Now we are going to generate an image and flash it to the microSD card. First plug in your microSD card to your computer. If your computer doesn't have a microSD card slot, (which it probably doesn't), then use either an microSD to SD adapter, or a microSD to USB adapter.

Now we need to locate the drive name. Use lsblk -p to list your drives.

pizzalovingnerd@pizzalovingnerd-ThinkPad-X230:~$ lsblk -p
NAME             MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
/dev/sda           8:0    0 465.8G  0 disk 
├─/dev/sda1        8:1    0   512M  0 part /boot/efi
├─/dev/sda2        8:2    0     1K  0 part 
└─/dev/sda5        8:5    0 465.3G  0 part /
/dev/mmcblk0     179:0    0  59.5G  0 disk 
└─/dev/mmcblk0p1 179:1    0    49M  0 part

If you are using a microSD to SD card adapter, your drive name should be something along the lines of /dev/mmcblkX where X is a number.

But if you are using a microSD to USB adapter, then it will be something along the lines of /dev/sdX where X is a drive letter.

Flashing to an SD Card

If you want to flash postmarketOS to your microSD card, then run pmbootstrap install --sdcard /dev/drive where drive is either sdX or mmcblkX. Run this at your own risk. This will overwrite all data on the drive.

Flashing to the EMMC

If you want to flash postmarketOS to the PinePhone's EMMC, or it's local storage, then you we we will have to use Jump Drive.

First we are going to download Jumpdrive using wget, and then convert the .img.xz file to a .img file using unxz. Then we will flash Jumpdrive onto the SD card.

wget https://github.com/dreemurrs-embedded/Jumpdrive/releases/download/0.4/pine64-pinephone.img.xz
unxz pine64-pinephone.img.xz
sudo dd bs=4M if=pine64-pinephone.img of=/dev/drive

Now insert the SD card with Jumpdrive into the PinePhone. And reboot. You should get something like this on your PinePhone.

Now if we run lsblk -p it will show two new drives.

pizzalovingnerd@pizzalovingnerd-ThinkPad-X230:~$ lsblk -p
NAME        MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
/dev/sda      8:0    0 465.8G  0 disk 
├─/dev/sda1   8:1    0   512M  0 part /boot/efi
├─/dev/sda2   8:2    0     1K  0 part 
└─/dev/sda5   8:5    0 465.3G  0 part /
/dev/sdb      8:16   1  14.7G  0 disk 
└─/dev/sdb1   8:17   1  14.7G  0 part 
/dev/sdc      8:32   1  59.5G  0 disk 
└─/dev/sdc1   8:33   1    49M  0 part

/dev/sdb is the PinePhone's EMMC, and /dev/sdc is the SD Card.

And now we can run pmbootstrap install --sdcard /dev/sdX to flash postmarketOS to the PinePhone's EMMC.

pmbootstrap install

When we run pmbootstrap install it creates a chroot with the installation, which is then copied to an encrypted image. Eventually it will ask you for a password. Note: the password may be hidden depending on your terminal emulator.

[12:47:11] *** (2/5) CREATE DEVICE ROOTFS ("pine64-pinephone") ***
[12:47:11] Update package index for aarch64 (4 file(s))
[12:47:13] (native) install qemu-aarch64
[12:47:13] Register qemu binfmt (aarch64)
[12:47:13] (rootfs_pine64-pinephone) install alpine-base
[12:47:18] (rootfs_pine64-pinephone) install postmarketos-base device-pine64-pinephone device-pine64-pinephone-nonfree-firmware postmarketos-ui-phosh
[12:49:10] (rootfs_pine64-pinephone) write /etc/os-release
[12:49:10] (rootfs_pine64-pinephone) install
[12:49:14] (rootfs_pine64-pinephone) install
[12:49:19] (rootfs_pine64-pinephone) mkinitfs postmarketos-allwinner
[12:49:58]  *** SET LOGIN PASSWORD FOR: 'pizzalovingnerd' ***
New password:

Eventually, it will be done installing. Now just run pmbootstrap shutdown and will are done. Now if you boot into your PinePhone, you should see postmarketOS.

ERROR: /dev/sdXX is mounted!

If you an error similar to this: ERROR: /dev/sdXX is mounted! We will not attempt to format this! then run sudo umount /dev/sdX?* and it should work when you run pmbootstrap install again.

Otherwise, you are all set.

Thank you for reading, if you like my work, please become a patron, or donate another way, and join the PizzaLovingNerd community on the chat protocol of your choice.