PinePhone postmarketOS upgrade

published on • last edited on

After watching Nathan Freitas’ Libreplanet 2021 keynote on “Ten years of empowering activists AND everyday people through free mobile software” in which he briefly mentioned the PinePhone, I grabbed mine from the bottom drawer of my wardrobe and booted it up for the first time in a while.

After fooling around with it for a little and upgrading the installed software packages, I noticed an “Upgrade” app which I had not seen before: It turns out that a new postmarketOS version has been released.

So, I went to work on upgrading my PinePhone.


My efforts were initially stopped short, as I did not have a free microSD card at hand. Make sure you have one available which you can temporarily use (once you’re through with the postmarketOS upgrade you are free to use it as you wish again) and flash (all data currently on the microSD card will be deleted).

Upgrade steps

The following steps describe what I did to update my PinePhone to the new “stable”1 postmarketOS v21.03. I have largely followed the postmarketOS installation tutorial for the PinePhone but felt like it lacked structure at times (mostly due to the fact that it covers many different options). I hope this guide can clear up some ambiguity.

  1. Decide from which device you want to flash your microSD card. You can do it from any desktop computer/laptop running GNU/Linux if you have a microSD card reader/adapter. Alternatively, you can just use the PinePhone itself (in this case, I’d recommend you to SSH into your PinePhone to avoid typing long commands on the phone; it is not necessary though).

  2. Make a backup of your home directory via rsync over SSH, in case you want to save data from your phone’s /home directory. This step is optional, but recommended. It requires a second device.

  3. Download the right postmarketOS image for the PinePhone.

    1. Open the postmarketOS builds directory. Select the interface you want to use, then choose the latest build date. From the resulting directory download the ...installer.img.xz and the ...installer.img.xz.sha512 files:

      $ cd Downloads
      $ wget <link to ...installer.img.xz file>
      $ wget <link to ...installer.img.xz.sha512 file>
    2. Check the downloaded installer image for corruption:

      $ sha512sum -c <path to ...installer.img.xz.sha512 file>

      This step is optional but recommended.

  4. Flash the downloaded image to the microSD card: 0. Plug in the microSD card into the device from which you want to flash it. If you’re using the PinePhone for the upgrade, make sure to not put the microSD in the SIM card slot.

    1. Now you have to figure out the device name of your microSD card. The safest way to do this is to run lsblk once with the microSD inserted, remove the microSD card, run lsblk again, and see which entry has disappeared. Alternatively, if your microSD card has a different size than all other storage devices, you can run

      $ lsblk
      # mmcblk0      179:0    0 59.5G  0 disk
      # └─mmcblk0p1  179:1    0 59.5G  0 part
      # mmcblk2      179:32   0 14.5G  0 disk
      # ├─mmcblk2p1  179:33   0  121M  0 part /boot
      # └─mmcblk2p2  179:34   0 14.3G  0 part
      # mmcblk2boot0 179:64   0    4M  1 disk
      # mmcblk2boot1 179:96   0    4M  1 disk

      only once and determine the device name of the microSD card by looking for the device with the size of your microSD card. Make sure that the type of the device is disk not part.

    2. With the microSD inserted, flash the image to the microSD device with

      # if you're flashing on a secondary device
      $ xzcat <path to ...installer.img.xz> | sudo dd of=/dev/<microSD card device name> status=progress
      # if you're flashing on the PinePhone
      $ xzcat <path to ...installer.img.xz> | sudo dd of=/dev/<microSD card device name> status=noxfer

      Wait for dd to finish.

    3. Double check with lsblk whether the microSD card device has some new pmOS partitions.

  5. Switch off the PinePhone. Insert the microSD card into the PinePhone’s microSD slot in case it was not there yet. Boot the phone again.

  6. Walk through the instructions of the graphical installer. Once the installer is done, switch off the phone, remove the microSD card from the phone (in case you selected to flash to the eMMC - the phone’s integrated storage device - during the graphical installer process), and start the phone again.

  7. Verify that the new postmarketOS version is installed by opening the “Settings” app and going to “Details > About > OS Name”. You should see something along the lines of “postmarketOS v21.03.x”.

  8. Wipe the microSD card by connecting it to a GNU/Linux device and running:

    $ sudo dd if=/dev/zero of=/dev/<microSD card device name>

Closing thoughts

Big kudos to the postmarketOS project. They are doing difficult, yet very important work driven by a laudible motivation:

We are sick of not receiving updates shortly after buying new phones. Sick of the walled gardens deeply integrated into Android and iOS. That’s why we are developing a sustainable, privacy and security focused free software mobile OS that is modeled after traditional Linux distributions. With privilege separation in mind. Let’s keep our devices useful and safe until they physically break!

The developers appreciate your donations and contributions!

  1. It is the second beta release. ↩︎