Installation/Using a pre-built image

This page describes the process of installing postmarketOS using pre-built images.
== Preparation ==
* 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 ==
You can find pre-built images at postmarketos.org/install.
Selecting the release
Open postmarketos.org/install, then scroll down to the bottom. Find your device in the table.
On the right, you'll find links to images for the latest stable release or the edge release. Select the version you're interested in.
➜
Selecting the user interface and version
After you've selected the version, you will be taken to a folder selection page. On the first screen, select the folder corresponding to the user interface you would like to select. On the next screen, select the latest image.
➜
Selecting the images to download
You will be presented with multiple files to download. See the information below.
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 with the checksums returned by the following commands:
$ 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 ==
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 ===
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.
 Partition on the device
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:
{| class="mw-collapsible mw-collapsed"
* 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.
=== 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.
Category:Guide