Installation

From postmarketOS
Revision as of 10:09, 10 January 2023 by Ollieparanoid (talk | contribs) (→‎SD card: clarify: "flashing anything to internal storage")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

This article describes how to get postmarketOS installed onto your device.

Introduction

What to expect

In its current stage, postmarketOS is for Linux enthusiasts. The experience will not be as polished as running Android or iOS. Expect serious bugs like calls not working, SMS not arriving, alarm clock not working etc. Do not use this on your main phone if you rely on its functionallity. You have been warned.

Also in this stage, we expect that you know how to use a Linux terminal. Throughout this wiki you will find a couple of commands prefixed with $ (or # for root). You should not enter that character, it is merely to designate that the following commands are intended to be input/executed within a terminal. For example, the following command to list contents of the current working directory, ls, will be mentioned as:

$ ls

Your device

First of all, open the devices page in a new tab and find your device. Take notice of the category it is in (main, community or testing). Read the available features on the device page (so you don't have wrong expectations). The installation instructions vary greatly depending on your device, so make sure to read the device specific installation instructions.

Build your own image?

To install postmarketOS, you have two options:

  • Use a pre-built image if your device is in the main or community categories. Read on below.
  • Build your own image with pmbootstrap if your device is in the testing category, or if you would like to have more choices available (e.g. picking an exotic user interface). Read the pmbootstrap article.

Using a pre-built image

Download

Open the download page and click on your device. You will be presented with directories named after user interfaces. Choose one of them. Then click on the directory with the latest image date. Now you can download the image files.

Download the following files, each of them is described further below:

  • installer or rootfs
  • boot (if available)
  • bootpart (if available)

installer

Some devices have an extra installer image available. It ends in -installer.img.xz and contains the rootfs image, but wrapped in an installer that runs on your phone. Most importantly, this allows encrypting the installation. For devices that boot from SD card (e.g. PinePhone), it also allows installing from the SD card to the internal storage.

You will be able to set a user and encryption password during the installation.

Download either the installer or rootfs image.

rootfs

All devices have a rootfs image. It ends in the device name and .img.xz, for example -pine64-pinephone.img.xz.

The rootfs image is not encrypted. If you would like to encrypt your phone, but there is no installer image available for your device, you can build your own encrypted image with pmbootstrap instead of following this guide.

The rootfs image has the default login of user and password 147147.

Download either the installer or rootfs image.

boot

Androids need a boot.img file. It ends in -boot.img.xz.

Download it, if it is available.

bootpart

For some devices like the ASUS MeMO Pad 7, the root and boot partition are in separate files instead of being combined in the rootfs image (pmbootstrap!1871). The file containing the boot partition ends in -bootpart.img.xz.

Download it, if it is available.

Flashing

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 lsblk 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 /dev/mmcblk0.

Then write the image to it:

$ xz --decompress --stdout path-to-rootfs-or-installer.img.xz | sudo dd of=/dev/mmcblk... bs=4M status=progress

If you are on Windows, see here.

Wait until the command completes and eject the SD card. If your device is able to boot from SD card without flashing anything to internal storage (such as the PinePhone), you should now be able to insert it into your device and boot it up. If you have chosen the installer image, follow its instructions. The rootfs image will boot right into postmarketOS. You are done with installing postmarketOS, congratulations!

Flash tools like Fastboot, Heimdall etc.

Other devices, such as Androids and the Librem 5 need to run a flashing tool to send the image files to the device while it is in a special flashing mode. Beware that this will overwrite the existing installation/data on your phone! The device page should give the detailed instructions. Usually it involves extracting the images (as these tools can't use the xz compressed files), with the unxz command. Afterwards one runs the flash tool with it, e.g. fastboot flash ….

If the instructions are missing, look at your device's deviceinfo file or ask in the chat for help. Then add the missing instructions for the next person.

When you are done with flashing the files, reboot the device. You are done with installing postmarketOS, congratulations!

See also