Open main menu


Revision as of 08:50, 31 August 2020 by Ollieparanoid (talk | contribs) (troubleshooting: mention .xsession-errors)


Using pmbootstrap, Phosh can be installed by selecting it as the UI in pmbootstrap init.

On existing systems, it can be installed by installing the postmarketos-ui-phosh meta package or phosh if postmarketOS specific customization is not wanted.

When running pmbootstrap install to flash a phone or sd card you'll be prompted for a user password. Make sure to only use numeric characters [0-9] in this password as the phosh lock screen uses this password as a pin. On an existing phosh install you can change your user password and pin in the terminal with the standard passwd command.


First Boot

If you get stuck, head over to Matrix and IRC chats. Report issues.

As with all other interfaces in postmarketOS, the first boot takes longer than usual: the file system will be resized to use the entire device. The first start of Firefox also takes longer than the following starts.

Install updates and reboot

GNOME software with updates available

Unless you have just built your own postmarketOS image a few minutes before doing the installation, it is highly recommended to install updates and then reboot your device. To do that, open the "Software" app, tap the "Updates" button on the bottom right. Then tap "Update All".

Once all updates are installed, reboot so you are actually using the newly installed software and not still the old versions. To do that, tap the top bar between the clock and the battery icon, tap the power symbol and then "Restart".

Do not report issues unless you have made sure that you have rebooted into an up-to-date system.

SSL handshake failed notification

The notification 'Unable to download updates from "" ... SSL handshake failed' can be ignored. Just tap the "x" at the bottom, so it does not cover the "Update All" button anymore.

This message appears if you have just connected to Wi-Fi, and your device's date was not synced with the Internet yet (see the clock that is visible in the top bar). Then GNOME software will fail to download some software ratings via the secure HTTPS protocol, because it can't verify the server's certificates without knowing the date (as they could have expired). For our use case, this is all irrelevant: we don't need the software ratings right now, we want to do updates. Because these updates are signed with a different mechanism already, we don't use HTTPS, but instead the plain HTTP to download them. So we don't even need to have the date synced.

Enable SSH

It's highly recommended to enable and test SSH access to your phone, so you can control your phone from the terminal, transfer files and take part in development.

Contacts, SMS and calls

Unlock SIM card

If your SIM card needs a PIN, Phosh will display a SIM card icon with a question mark on top in the top bar. Open the top menu (tap between clock and battery icon), then tap the bigger SIM card icon again to type in the PIN.

Manage contacts

It's currently impossible to use created contacts for making calls or writing SMS (pmaports#730, pmaports#729, calls#88). Until that is fixed, adding contacts is not really useful.

Open the bottom menu, and open the "Contacts" app (blue book with @ sign). The "Contacts Setup" screen will appear. Select the "Local Address Book" (read below for more options) and "Done". An empty contact list appears.

Hit the + button on the left to add a contact. The screen appears to be stuck (pmaports#728). If you go to the bottom menu (tap the bottom arrow) and open the app again, the "New Contact" screen appears.

Fill out at least the name and phone number, then hit "Add" on the top right.

Synchronization with an online account

For convenience, some people may choose to synchronize their contacts with an online account. In order to do that, close the "Contacts" app (otherwise "Settings" will not open). Then open "Settings" from the bottom menu. Select "Online Accounts" and then add a provider where contact synchronization is supported). After you have added your online account, you should be able to select it in the "Contacts" app.

Note that the online account providers also list services, which are known bad actors in regards of privacy (pmaports#725). From a privacy and anti-mass-surveillance point of view, the best solution is not using contact synchronization at all, or using a self-hosted solution (e.g. with Nextcloud).

Make a call

Open the calls app, select "DialPad" at the bottom and type in the number to make a call. After doing this for the first time, the number appears in "Recent" and can be called from there. If you want to avoid typing in a number, consider calling the phone running Phosh from another phone. Then the number will appear in "Recent" as well and can be called back.

When pmaports#730 is fixed, it will be possible to start a call from the contacts app. calls#88 is about making it possible the other way around (selecting the contact from the calls app).

Write SMS

Open the "Chats" app (the one with two message bubbles). Write an SMS to your phone running Phosh to start a conversation.

Writing to a previously added contact is currently broken (pmaports#729).

Install software

The "Software" app doesn't show the applications available in postmarketOS and Alpine yet (pmaports#699). The best way to install new software is currently via SSH with Alpine's package keeper (apk, no relation to the Android app format). Use apk search to find software, and apk add to install it. Read apk -h for usage information.

To install the PDF reader Evince for example:

$ sudo apk add evince

Take a screenshot

Currently there is no way to take a screenshot directly from the user interface, however you can take a screenshot from the terminal!

First install grim using sudo apk add grim. Invoking grim results in a screenshot of the entire screen being saved into the current working directory.

If you need to delay the screenshot for e.g. 10 seconds you can do that as well: sleep 10 && grim.

If you need to invoke grim from an SSH session you need to first log in as the user account (su - user) and then invoke grim with a special environment variable: XDG_RUNTIME_DIR=/run/user/10000 grim.


Starting Phosh

If postmarketos-ui-phosh is installed, Phosh will be automatically launched via the LightDM display manager.

It can also be launched manually by running dbus-run-session /usr/bin/phosh.

Screen Scaling

The Phosh screen may be scaled lower for better compatibility with existing applications. Change the scale by modifying the scale factor variable found in /usr/share/phosh/phoc.ini, which has a default value of 2.

Screen scaling may also be performed on-demand from the command line or by making an application by following the Purism Easy Librem 5 App Development: Scale the Screen blog post. Those instructions work well for devices running Phosh even if written for a Librem5 running PureOS (Debian-based OS). Keep in mind some commands will need to be modified to work on postmarketOS.


If you have trouble configuring everything with the graphical dialogs or just want to use the terminal, read along.

Unlock your SIM card with the PIN: mmcli -i 0 --pin=12345

Configure your APN for mobile data (example for mobile vikings in Belgium): mmcli -m 0 --simple-connect=',user=web,password=web,pin=1111'


Phosh related applications are logging to ~/.xsession-errors. It's recommended to only share the relevant piece of the log file, read through it and redact personal information (your phone number!) before sharing.

$ su - user
$ tail -f ~/.xsession-errors

See also