User:Knuxfanwin8/Installation guide rework/Using a pre-built image

&lt; Installation ‎ 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 if your device is in the "main" or "community" category. Pre-built images for devices in the "testing" category are not available - 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.

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

Quick glossary

 * Boot partition - this refers to the /boot partition on Android devices, which contains the kernel and initramfs.
 * 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 image
You can find pre-built images at postmarketos.org/download. 

Selecting the release
Open postmarketos.org/download, 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. Download either this, or the on-device installer:
 * {codename}-installer.img.xz, which allows you to set up your device (selecting an username, enabling disk encryption, etc.) before using it. Note that the on-device installer is only available on a few specific devices.

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 weird boot 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 file by running:

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

Flashing the image
At this point, read the Installation section in 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).

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:

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 where to install it.

In the case of Android devices, the standard Android OS is split into "system" and "data" partitions. 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 data 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.

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

Flashing rootfs to the SD card
The process is pretty much the same for all devices:


 * Find the name of your SD card using . You should get a path like  . Make sure that you have the right path - otherwise, you WILL lose your data!
 * Run, 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 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.

Flashing rootfs to a partition on the device
The exact process will differ based on which device you have, so check your device's wiki page before continuing.

Fastboot:
 * Plug the device into your computer and enter flashing mode.
 * Run  to make sure your device is detected.
 * Run  to flash to the system partition or   to flash to the data partition.

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!''
 * Enter download mode (usually this is done by pressing Power+VolDown+Home).
 * Run  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 device will reboot; reboot it back into download mode.
 * Run, replacing PARTITION with the partition you got in the above command.

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

''For a small subset of Samsung devices using Heimdall, the boot partition is named KERNEL, and BOOT is used for the bootloader. Make sure to check your device's wiki page, and verify with print-pit to be 100% sure!''

Finishing up
Once you've flashed all of the relevant images, reboot the device. If you did everything correctly, you should now be running postmarketOS! Here are some things you can do with your newly-flashed device:


 * Find apps to install by looking at the Applications by category page
 * Set up Waydroid to run Android apps on Linux
 * Post a screenshot of your setup on social media and share it with our community!

You can gather more ideas by checking out the Dogfooding category.