Jump to content

Installation: Difference between revisions

From postmarketOS Wiki
weird bug, nothing showed up
Tag: Undo
Choosing an installation method: simplify explanation
 
(25 intermediate revisions by 8 users not shown)
Line 1: Line 1:
This article describes how to get postmarketOS installed onto your device.
This page goes over the process of installing postmarketOS on your device.


== Introduction ==
== What to expect ==
=== 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 <code>$</code> (or <code>#</code> 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, <code>ls</code>, will be mentioned as:
{{Hatnote|''See also: [https://postmarketos.org/state/ State of postmarketOS]''}}


<source lang="shell-session">
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. For some devices, primarily in the "testing" category, features like calls may not work at all. Do not use this on your main phone if you rely on its functionality.
$ ls
</source>


=== Your device ===
It is expected that you are comfortable with using the Linux terminal. On this wiki, you may find commands prefixed with <code>$</code> or <code>#</code>. These characters shouldn't be copied - they indicate whether that command should be run as a regular user (<code>$</code>), or as root (<code>#</code>).
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? ===
For example, the following tells you to execute the command "ls" as a regular user:
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.
<syntaxhighlight lang="shell-session">
* 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.
$ ls
</syntaxhighlight>


== Using a pre-built image ==
== Finding your device ==
=== Download ===
Open the [https://postmarketos.org/download/ download] page and click on your device. You will be presented with directories named after [[:Category:Interface|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:
Before you begin installing postmarketOS, make sure to '''read your device's wiki page'''. It contains a lot of useful information, such as a list of supported features and installation methods. You can find it by checking the [[Devices]] list or by using the search feature on the wiki.
* installer or rootfs
* boot (if available)
* bootpart (if available)


==== installer ====
If you cannot find your device on the wiki, or if it's listed as non-booting, it is likely unsupported. If you're adventurous, you can follow the [[Porting to a new device|Porting guide]] to add support for your device.
Some devices have an extra installer image available. It ends in <code>-installer.img.xz</code> 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.
== Choosing a release channel ==


Download either the installer or rootfs image.
{{See also|Releases}}


==== rootfs ====
There are usually two release channels of postmarketOS available:
All devices have a rootfs image. It ends in the device name and <code>.img.xz</code>, for example <code>-pine64-pinephone.img.xz</code>.


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.
* '''stable''' - the stable release, based on the latest Alpine Linux version. Currently, the latest stable release is '''{{Latest stable release}}'''.
* '''edge''' - the rolling-release version, based on Alpine Linux's edge repositories. Gets the latest updates as soon as they hit the package repositories, and can thus be less stable. Expect breakages - see [https://postmarketos.org/edge/ postmarketos.org/edge] for more information.


The rootfs image has the default login of <code>user</code> and password <code>147147</code>.
If you're unsure, go with the stable release; you can [[Upgrade to a newer postmarketOS release#Upgrade to another channel|switch to the edge branch]] later.


Download either the installer or rootfs image.
== Choosing an installation method ==


==== boot ====
There are two primary methods of installing postmarketOS. You can:
Androids need a [[boot.img]] file. It ends in <code>-boot.img.xz</code>.


Download it, if it is available.
<div style="margin: 1.5em; display: flex; gap: 0.5em; align-items: center; flex-wrap: wrap; justify-content: center;">
{{Large link box
|icon=Icon-numix-light-drive-multidisk.svg
|target=Installation/Using a pre-built image
|label=Use a pre-built image
|body=<span style="padding: 0 2px 4px; font-size: 1.15em; display: block;">For select devices, mostly from the '''main''' and '''community''' categories</span>
<ul style="text-align: left;">
<li>Quickest and simplest option - no configuration needed, flash it and you're good to go</li>
</ul>
}}<!--
--><span style="padding: 0.5em; display: block;">-&nbsp;or&nbsp;-</span><!--
-->{{Large link box
|icon=Icon-numix-light-applications-engineering.svg
|target=Installation/Using pmbootstrap
|label=Install with pmbootstrap
|body=<span style="padding: 0 2px 4px; font-size: 1.15em; display: block;">For '''all''' devices, including those that do not have images available</span>
<ul style="text-align: left;">
<li>Provides more customization options: select your own UI, pre-installed packages, options for developers/advanced users</li>
</ul>
}}
</div>


==== bootpart ====
Other options include:
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 ({{MR|1871|pmbootstrap}}). The file containing the boot partition ends in <code>-bootpart.img.xz</code>.


Download it, if it is available.
* Installing through the [https://flash.postmarketos.org/ postmarketOS web flasher] - only available for a few devices with pre-built images. Requires a Chromium-based browser (due to its usage of the non-standard WebUSB interface).
* Installing through the recovery using Android-recovery compatible .zip - see [[Installation from recovery mode]]
* Installing through the [https://devices.ubuntu-touch.io/installer/ UBports Installer] (only available for a few devices in the main/community repositories) - select postmarketOS in the OS selection dropdown


=== Flashing ===
== See also ==
==== 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 <code>lsblk</code> 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 <code>/dev/mmcblk0</code>.
 
Then write the image to it:


<source lang="shell-session">
* [[Dual Booting]]
$ xz --decompress --stdout path-to-rootfs-or-installer.img.xz | sudo dd of=/dev/mmcblk... bs=4M status=progress
* [[Upgrade to a newer postmarketOS release]]
</source>
 
If you are on Windows, see [[Windows_FAQ#Flashing_images_to_SD_cards|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 [[devices|device page]] should give the detailed instructions. Usually it involves extracting the images (as these tools can't use the <code>xz</code> compressed files), with the <code>unxz</code> command. Afterwards one runs the flash tool with it, e.g. <code>fastboot flash …</code>.
 
If the instructions are missing, look at your device's [[deviceinfo]] file or ask in the [[Matrix and IRC|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 ==
* [[pmbootstrap]]
* [[Existing Alpine installation]]
* [[Existing Alpine installation]]
* [[Porting to a new device]]
* [[Porting to a new device]]
* [[Troubleshooting]]


[[Category:Guide]]
[[Category:Guide]]

Latest revision as of 02:26, 20 February 2025

This page goes over the process of installing postmarketOS on your device.

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. For some devices, primarily in the "testing" category, features like calls may not work at all. Do not use this on your main phone if you rely on its functionality.

It is expected that you are comfortable with using the Linux terminal. On this wiki, you may find commands prefixed with $ or #. These characters shouldn't be copied - they indicate whether that command should be run as a regular user ($), or as root (#).

For example, the following tells you to execute the command "ls" as a regular user:

$ ls

Finding your device

Before you begin installing postmarketOS, make sure to read your device's wiki page. It contains a lot of useful information, such as a list of supported features and installation methods. You can find it by checking the Devices list or by using the search feature on the wiki.

If you cannot find your device on the wiki, or if it's listed as non-booting, it is likely unsupported. If you're adventurous, you can follow the Porting guide to add support for your device.

Choosing a release channel

See also: Releases

There are usually two release channels of postmarketOS available:

  • stable - the stable release, based on the latest Alpine Linux version. Currently, the latest stable release is v24.12.
  • edge - the rolling-release version, based on Alpine Linux's edge repositories. Gets the latest updates as soon as they hit the package repositories, and can thus be less stable. Expect breakages - see postmarketos.org/edge for more information.

If you're unsure, go with the stable release; you can switch to the edge branch later.

Choosing an installation method

There are two primary methods of installing postmarketOS. You can:

Use a pre-built image

- or -

Install with pmbootstrap

Other options include:

  • Installing through the postmarketOS web flasher - only available for a few devices with pre-built images. Requires a Chromium-based browser (due to its usage of the non-standard WebUSB interface).
  • Installing through the recovery using Android-recovery compatible .zip - see Installation from recovery mode
  • Installing through the UBports Installer (only available for a few devices in the main/community repositories) - select postmarketOS in the OS selection dropdown

See also