Installation/Using a pre-built image

This page describes the process of installing postmarketOS using pre-built images.

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.

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.
Check the "Pre-built images" status in the infobox on the device's page or check the table at postmarketos.org/download to see if there's an image available for your device.
- Images are available for all devices in the "main" and "community" categories, as well a few select devices from the "testing" category.
- If your device is not listed there, use pmbootstrap to install postmarketOS instead.
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.

This guide assumes you're running Linux, and have root access as well as access to a terminal.

Quick glossary

Boot partition - the partition containing the kernel and initramfs. On Android devices, this is often part of a "boot.img" file.
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.

Downloading the images

The screenshots below are provided for illustration purposes and may not be up-to-date.

You can find pre-built images at postmarketos.org/download.

➜➜

First, download the rootfs image:

{codename}.img.xz - contains the rootfs, the main system partition.

Depending on your device, you may also have to download one of the following:

{codename}-boot.img.xz - contains the Android boot partition. Only available for Android devices.
{codename}-bootpart.img.xz - used by some devices (like the ASUS MeMO Pad 7 (asus-me176c)) which use a split boot/root layout.

These are only available for some devices, so don't worry if you can't find them in your device's images. As always, check the device's wiki page if you're unsure.

Verifying the downloaded files

This step is highly recommended. Doing this can allow you to avoid various issues that may be hard to debug otherwise.

Each of the downloaded files has a corresponding checksum in both sha256 and sha512 listed on the download page. Compare the checksums on the site with the checksums of your local files by running:

$ sha256sum path-to-image-file.img.xz
$ sha512sum path-to-image-file.img.xz

If they do not match, re-download the files.

Extracting the images

The images you have downloaded are compressed. In order to be able to flash them, we need to extract them from the archives.

Move the downloaded files to a separate directory, then for each of the archives run:

$ xz --decompress path-to-image-file.img.xz

You should now get .img files corresponding to the extracted archives. You can now remove the .xz files.

Choosing the rootfs destination

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

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.

Flashing the images

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

At this point, read the Installation section of your device's wiki page. This section goes over the general process of flashing images, but 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 rootfs

Click "Expand" next to the section titles to see the relevant instructions.

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

SD card
The process is pretty much the same for all devices: Find the name of your SD card using `lsblk`. You should get a path like `/dev/mmcblk...`. Make sure that you have the right path - otherwise, you WILL lose your data! If you're unsure, run `sudo fdisk -l /dev/[yourdevice]`, which should print some information about the device. Get the path without the partition suffix (for example - `/dev/mmcblk0` instead of `/dev/mmcblk0p1`). Run `sudo dd if=path-to-rootfs.img of=/dev/mmcblk... bs=4M status=progress`, replacing "path-to-rootfs.img" with the path to the image file you extracted earlier, and "/dev/mmcblk..." with the SD card's path. If you prefer to avoid using `dd`, there are also more user-friendly GUI programs which can flash an image to the SD card (for example Etcher). If you have a device that can boot directly from the SD card (such as the PINE64 PinePhone (pine64-pinephone)), you don't need to flash anything else. postmarketOS will try to resize the newly-added partition on first boot to fit the entire SD card. If that process fails, and you end up with a small rootfs partition, see #SD card install: Root partition is too small.

The exact commands will differ based on which device you have and what flashing protocol it uses. Follow the instructions on your device's wiki page.

In case there are no instructions on the wiki, follow these generic commands:

Fastboot
Download fastboot as part of the Android platform tools or from your distro's package manager (look for a package named something like `android-tools`). Plug the device into your computer and enter flashing mode. Run `fastboot devices` to make sure your device is detected. Run `fastboot flash PARTITION path-to-rootfs.img` to flash to the partition (replace PARTITION with either "userdata" or "system"). If you're flashing to the userdata partition, you may also want to wipe the system partition using `fastboot erase system`. When you're done flashing, reboot the device with `fastboot reboot`. Rebooting it through this command rather than powering off the device manually ensures that the data is written correctly.

Heimdall (Samsung Download Mode/Odin)
Many Samsung devices running the mainline kernel use a secondary bootloader like lk2nd, which provides a fastboot interface. Again, check the wiki page before flashing! Get heimdall from your distro's package manager or by building it from source. You can also use heimdall through pmbootstrap's chroot; run `pmbootstrap chroot apk add heimdall` then execute the next commands as `pmbootstrap chroot heimdall`. Enter download mode (usually this is done by pressing Power+VolDown+Home). Run `heimdall print-pit` to get a list of partitions. The system partition will usually be called SYSTEM, and the data partition will usually be called USERDATA or DATA. The boot partition (needed for the kernel flash) is usually called BOOT or KERNEL. The device will reboot; reboot it back into download mode. Run `heimdall flash --PARTITION path-to-rootfs.img`, replacing PARTITION with the partition you got in the above command.

Flashing the boot image

If you have an Android device, you'll likely have to flash the boot image/kernel as well. The process is largely the same as the one for flashing rootfs images to the device, but "system" is replaced with "boot".

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.

The default user account in pre-built images is named user; the default password is 147147. You should be able to log in using those credentials.

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

Downloading updates

The image you have installed from may have been slightly out of date. As such, once you have the system installed, it's highly recommended to run an upgrade.

To do this, make sure that you're connected to the internet, then run sudo apk upgrade -U in the terminal.

Finishing the configuration

After installing from a pre-built image, you may want to change some settings:

The timezone is not set up by default; you can change it in your UI's settings app.
You may want to change the default password - this can either be done through your UI's settings app, or by running passwd in the command line.

If you need help configuring your system, the wiki page for your interface may contain some helpful instructions.

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.

Fastboot/heimdall do not see any devices or report "permission denied" errors

You may need to install the relevant udev rules to allow your user to access the USB device without root access - see Troubleshooting#flasher (fastboot) is stuck in < waiting for any device > for instructions. As a workaround, you can also launch the flashing tool as root.

If this does not help:

Make sure your device is booted into its dedicated fastboot/download mode.
Try a different cable.

SD card install: Root partition is too small

Usually, postmarketOS tries to resize the partition on first boot; however, this may not work on some devices (particularily those not running a (Close to) Mainline kernel). For an SD card install, if you find that the root partition on your device doesn't fill all available space, you can try the following steps to resize it:

Plug the SD card into your computer. Get the path to the SD card, without the suffix (so, /dev/mmcblk0 instead of /dev/mmcblk0p1).
Run sudo fdisk /dev/mmcblk..., where /dev/mmcblk...> is the path you got in the previous step.
- Type p to list available partitions. You should see two partitions: a pmOS_boot and pmOS_root partition. Note down the number next to the root partition (usually 2) as well as the "Start" offset.
- Type d to delete the partition; when prompted, give the number of the root partition from the previous step.
  - This will not delete any data, just remove the partition from the partition table.
- Type n to recreate the partition. Follow the prompts:
  - Partition type: p (primary)
  - Partition number: the number of the partition from earlier.
  - First sector: the "Start" value of the original root partition.
  - Last sector: the default here should fill all available space, so just press Enter.
    - If you want a specific partition size, you can type e.g. +16GB, provided there's enough free space on the SD card.
  - Do you want to remove the signature: N. We don't want to remove the signature as that will cause us to lose the partition.
- Type p again and make sure the partition you made is set up correctly.
- Type w to write changes. This should also quit fdisk.
Run sudo e2fsck -f /dev/mmcblk...pX, where /dev/mmcblk...pX is the path to the device with the partition suffix. X should be replaced with the partition number from the partition list as seen earlier in fdisk.
Run sudo resize2fs -f /dev/mmcblk...pX, again replacing /dev/mmcblk...pX, to resize the partition.

Once this is done, the partition should be resized. You can try to mount it on your computer to make sure it worked.