Phosh is a phone shell based on the GNOME stack. It is developed by Purism for their own Linux smartphone, the Librem 5. With postmarketOS, it can be used on various other mobile devices too. We have shipped the PinePhone postmarketOS community edition with Phosh.
Default Phosh homescreen.
|Graphics stack||Phoc on Wayland|
- 1 Installation
- 2 Usage
- 2.1 First Boot
- 2.2 Contacts, SMS and calls
- 2.3 Install software
- 2.4 Take a screenshot
- 2.5 Camera
- 2.6 External monitor
- 2.7 postmarketos-tweaks
- 2.8 USB Tethering
- 3 Configuration
- 4 Troubleshooting
- 5 See also
Use the pre-built images from the downloads section of postmarketos.org, or build your own image with pmbootstrap. If using the latter, Phosh can be installed by selecting it as the UI in
On existing systems, it can be installed by installing the postmarketos-ui-phoshPMOS meta package or phosh if postmarketOS specific customization is not wanted.
pmbootstrap install 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 (but there is a keyboard button for entering a non-numeric password if you happened to have set one). On an existing Phosh install you can change your user password and PIN in the terminal with the standard
|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.
After boot, you are asked for your PIN. For pre-built images, this is
Install updates and reboot
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". When the updates are finished, all listed packages will disappear and you will be left with a screen showing only a horizontal line.
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".
After rebooting, update the "Software" app once again. If you are running the build that was shipped with the PinePhone, you will immediately see an update for
mobile-config-firefox (apk-polkit#18). Install this one too, so Firefox is configured for mobile. This tiny update does not need a reboot.
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 "odrs.gnome.org" ... 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.
This bug is tracked in pmaports#1407.
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.
If you see a "No WWAN Adapter Found" message, tap the toggle-icon on the top right. It should turn blue and a "SIM Locked" message screen should appear instead, with an "Unlock" button.
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.
+ button on the left to add a contact. 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).
Import contacts from a .vcf file
To import a .vcf file, open the "Contacts" app, click on the menu icon in the top right corner, and select "Import". A window will pop up allowing you to select your .vcf file. Once selected, click "Confirm" in the confirmation popup that shows up.
Make a call
Either open the "Contacts" app and tap on the call icon next to an existing contact. Or open the "Calls" app, select "DialPad" at the bottom and type in the number (selecting existing contacts from within the "Calls" app is currently not possible: calls#88).
Previously called contacts / typed in numbers and received calls appear in "Recent" and can be called again 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.
First install chatty with
sudo apk add chatty
Add the target phone number as contact (as described above). Then open the "Chats" app (the one with two message bubbles), hit the "+" on the top right, select the contact and start typing your SMS.
Alternatively, write an SMS from another phone to your phone running Phosh to start a conversation.
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 in your Pictures 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:
If grim tries to take a screenshot of the wrong output (e.g.
failed to copy output HDMI-A-1), specify the output with
grim -o output with an output from
ls /sys/class/drm without the
If your phone is able to make photos on postmarketOS (if unsure, check the device wiki page), run the Megapixels app to take photos.
If it is not installed already, and it does not show up in the "software" app (pmaports#699), install it via SSH:
$ sudo apk add megapixels
It is also recommended to install
nemo to view and browse the images that were taken. Both can be opened from Megapixels once installed. New installations of postmarketOS with Phosh will come with all three apps installed by default.
|PinePhone: this appears to be broken for some users, see: pmaports#1009|
Plug in a cable to your external monitor into your phone. Phosh should recognize the screen automatically and you should be able to use it. For the PinePhone, see this demo video.
Need a reminder of keyboard shortcuts to move applications between screens?
Install postmarketos-tweaks (via the Software app or
apk add postmarketos-tweaks), to get a graphical application that allows various tweaks. For example:
- Change the GTK theme to a dark one (dark mode)
- Change icon themes
- Change the time after which the phone suspends
- Enable or disable all animations
Once pmaports!3819 is merged to edge, USB tethering can be enabled as follows.
- Connect your phone over USB to your desktop.
- On the phone, open Settings
- Go to the Network panel tab.
- You should see 1 wired connection at the top, tab the edit settings button (gear)
- An old panel opens which doesn't fit your screen (use Phosh Mobile Settings to enable scale-to-fit for this panel only, it will be shown in the list of active apps).
- Go to the IPv4 tab.
- Select 'Shared to other computers' and tab the Apply button in the right corner.
The easiest way is
sudo service tinydm restart.
Explanation of Phosh starting process in pmOS
postmarketos-ui-phosh is installed, Phosh uses the GNOME login and session handling. A session is defined as the lifecycle of a user interaction with the system. Phosh will be automatically launched as a session using the login daemon
autologin credentials provider, and the
tinydm display manager.
The daemon actually managing the sessions is
elogind which is the login daemon used with GNOME environments not integrated with the desktop system daemon
systemd (Phosh on PostmarketOS currently does not use systemd).
elogind is responsible for restarting the session if it crashes, and terminating all active sessions when the system powers off. Each user session occurs at a seat. Usually there will be just one seat: the session interacting with the screen. However if you also use a console (such as a serial port) this also becomes a seat.
On the way up the
elogind session interacting with the main screen seat will proceed to start the display manager
tinydm (TinyDM website) using
autologin to provide the default user with Wayland as the display server. On PostmarketOS the default user will be user ID 10000 which is what the installation scripts have set up.
Tinydm in turn will launch Phosh by looking into the file
/var/lib/tinydm/default-session.desktop which contains an
Exec directive executing
dbus-run-session /usr/bin/phosh which in turn will produce the passcode screen so you can proceed to log into your phone.
It can also be launched manually by running
The Phosh screen may be scaled lower for better compatibility with existing applications. Change the scale by modifying the scale factor variable found in /etc/phosh/phoc.ini. If the default value was not set in postmarketOS' device configuration, then the setting will be in /usr/share/phosh/phoc.ini instead.
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.
scale-to-fit it is possible to scale selected applications so they fit the screen:
$ scale-to-fit $APPID true
$APPID may be determined as follows
$ WAYLAND_DEBUG=1 $COMMAND 2>&1 | grep 'xdg_toplevel@[0-9]\+\.set_app_id'
$COMMAND is the application's executable name. For further reference, look at LINMOB's article about scaling.
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='apn=web.be,user=web,password=web,pin=1111'
Phosh uses feedbackd for haptics, the source repo is hosted on Purism's GitLab, device specific configuration files are hosted in the feedbackd-device-themes repo.
Feedbackd supports devices using the
EV_FF (force feedback event) via the Linux input API, the pm8xxx-vibrator driver is a good example implementation of this.
Currently, feedbackd supports the Librem 5, PinePhone and most recently OnePlus 6/6T (and soon the PocoPhone F1). However it should be possible to get any MSM8996+ device working (and MSM8916), as long as the hardware is supported by the mainline driver.
For more details see Haptics.
See also Debugging the GNOME stack.
Firefox looks weird
Firefox should look like this (on the right) after installing all updates. If the address bar is cut off, you don't have
mobile-config-firefox installed. Make sure you have installed all updates, rebooted, and checked for updates again (as described in install updates and reboot above).
If you would like to contribute to mobile-config-firefox, see the related project page.
Reading the log
Phosh related applications are logging to
~/.local/state/tinydm.log. 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. Login via SSH, then read the file:
$ su - user $ tail -F ~/.cache/tinydm.log
It is possible to manipulate the elogind user sessions as root using
loginctl. For example:
sudo loginctl list-sessionswill list the ongoing sessions, and on a normal phone or tablet you should have a one session called c1 connected to seat0.
sudo loginctl seat-status seat0will display the graphics, input and sound devices that seat0 for session c1 is connected to. This is a good way to verify that your graphics (both GPU and display controller), input, and sound devices are correctly set up.
sudo loginctl unlock-session c1will unlock the screen lock from the command line, if the screen happened to lock on you. (This does not apply to the login screen though, you still have to log in properly.)
sudo loginctl terminate-session c1will terminate the session and bring you back to the login screen. You will see a new cN session spawning (such as c3) since the session number increment by one for every new session.
See also the official documentation at Freedesktop.org.
Some apps don't show up in the shell / Terminal apps don't open
Some apps are currently hidden from the shell by postmarketos-hidden-desktop-entries. This mainly consists of terminal apps as these currently do not work in Phosh unless you install an alternative terminal emulator, e.g. GNOME Terminal. King's Cross (the default terminal emulator in Phosh) does not support launching terminal apps from desktop files it seems. It is also debated how useful these are in a mobile shell.