This page contains outdated information

Even though the community does its best to provide reliable and up-to-date information, the "Linux on Mobile" space still evolves quite quickly; as a consequence, a significant portion of the information on this page is outdated and do not describe current best practices accurately.

We invite you not to blindly trust the information present on this page and, whenever needed and possible, to update outdated instructions based on the current state of the art.

About this page

This page lists some commonly asked about customizations or tweaks that depend on user's preferences.

This page has quite a bit of overlap with the Frequently Asked Questions page, so check if your topic can be found there?

Automatic app scaling

As of version 0.4.0, phoc is now able to automatically scale down windows which are too large to fit the screen. This should be enabled on a per-app basis using the following command:

The APP-ID depends on how the app itself declares it, here is a small list:

Note: To find out the APP-ID, you can launch your app with WAYLAND_DEBUG=client and check for a line similar to xdg_toplevel@37.set_app_id("gedit").

To resize the Evolution reminders window (not launchable and not an app), the app id is evolution-alarm-notify.

Linmob.net has a post elaborating on scaling techniques (app vs full screen).

Alternatively, if you want a gui option, you can install PMOS-tweaks using the commands below and go to the "compositor" section and choose the app that you want to scale:

 git clone https://gitlab.com/postmarketOS/postmarketos-tweaks.git
 cd postmarketos-tweaks
 sudo apt install libhandy-1-dev python3-yaml meson
 meson setup --prefix=/usr build
 cd build
 sudo ninja install

Scale the screen

Sometimes apps just don't fit the screen and you would like to scale the full screen. Fortunately that is easy. "Settings->Display" has a setting to chose between 100% or 200% scaling. If you want to use other values or you need a way to do that from the terminal, install package wlr-randr and do:

(depending on which scale you want). The scaling is applied until you reboot, so is not saved permanently. You can also chose fractional values (1.5), but be aware that this could have performance implications. (It would be great if somebody tested this). This puri.sm blog post has a nice description on how to put together a mini app that allows you to easily change the scaling on the fly.

Scale the screen (variant 2)

The default configuration of phoc is in file /usr/share/phosh/phoc.ini. To change the default screen scaling copy that file to /etc/phosh/phoc.ini and modify this part:

...
[output:DSI-1]
# scale = 2
scale = 1.5 
...

This change is persistent across reboots. (but beware that in case the default values of phoc.ini change at some point, you might end up with obsolete ones).

Change the background for the lock screen, app grid and monitor

To change the background for the app grid and/or lock screen, you need to create a file ~/.config/gtk-3.0/gtk.css. Here is an example css file:

/*
 * ~/.config/gtk-3.0/gtk.css
 * Restart phosh using "sudo systemctl restart phosh"
 */

phosh-app-grid {
  background-image: linear-gradient(rgba(0, 0, 0, 0.7), rgba(0, 0, 0, 0.7)),
                    url('file:///home/mobian/Pictures/background.jpg');
  background-size: cover;
  background-position: center;
}

phosh-lockscreen, .phosh-lockshield {
  background-image: linear-gradient(rgba(0, 0, 0, 0.7), rgba(0, 0, 0, 0.7)),
                    url('file:///home/mobian/Pictures/background.jpg');
  background-size: cover;
  background-position: center;
}

To change background of a monitor/background while loading an app run this command:

Proximity sensor

The proximity sensor on your phone is intended to detect infrared (IR) electromagnetic radiation from a distance of a few cm or less from your ear (during a phone call) or body (when the phone is in a pocket). Several components of software are involved in converting the measured "raw" integer value into either "near" (high value, e.g. 500) or "far" (low value, e.g. 10), depending on whether it is above or below the proximity "near level", and in taking an action in response to that. The measured raw value when no human IR is nearby will vary depending on conditions such as GPU/CPU temperature and ambient temperature. (Example: PinePhone v1.2, raw value from 8 to 22 at median GPU/CPU temperature of 50 to 55 deg C; raw value 18 to 22 at GPU/CPU 30-35 C; feel free to help with collecting proximity_raw data so that we can choose a better default.) You will likely have to modify the default "near level" so that screen blanking happens at the distance appropriate for your phone and specific sensor (e.g. stk3311-compatible), within the range of conditions in which you use your phone.

Browse the advice in /lib/udev/hwdb.d/60-sensor.hwdb .

1. As an ordinary user, estimate your preferred near level with a loop such as

for ((i=0;i<30;i++)); do cat /sys/devices/platform/soc/1c2b000.i2c/i2c-1/1-0048/iio:device0/in_proximity_raw ; sleep 1; done

for the PinePhone v1.2. The path for your particular phone may differ (e.g. .../iio:device1/... also for a PinePhone v1.2) - see /lib/udev/hwdb.d/60-sensor.hwdb for hints. Move your hand near the sensor. To see the boot-up near level that that is set via the device tree '.dtb' file, do cat /sys/devices/platform/soc/1c2b000.i2c/i2c-1/1-0048/iio:device0/in_proximity_nearlevel . For a no-reboot method, try the hwdb method (step 2), or if it fails, then the udev rules method (step 3) instead.

2. hwdb method:

2.1 As root, create a file /etc/udev/hwdb.d/61-sensor-local.hwdb :

sensor:modalias:of:Nlight-sensorT*Csensortek,stk3311:*
  PROXIMITY_NEAR_LEVEL=70

where 70 is the near level that you want to try, and /lib/udev/hwdb.d/60-sensor.hwdb gives hints for working out the specific text string for the sensor:modalias:... line (the current line appears valid for PinePhones as of 2022/2023).

2.2 Reload the udev system and restart the monitoring daemon with

sudo systemd-hwdb update && sudo udevadm trigger && sudo systemctl restart iio-sensor-proxy

3. udev rules method: First do the check in step 4. If it succeeds, then don't do step 3 (it's not needed).

3.1 As root, create a file /etc/udev/rules.d/10-proximity.rules with some useful comments starting with # and the line

ACTION=="add", SUBSYSTEM=="iio", TEST=="in_proximity_raw", ENV{PROXIMITY_NEAR_LEVEL}="70"

where 70 is the near level that you want to try.

3.2 Reload the udev system and restart the monitoring daemon with

sudo udevadm trigger --action=add && sudo systemctl restart iio-sensor-proxy

4. Check that the udev system has been updated, e.g.

sudo udevadm info --export-db |grep -i --color -C5 proximity_near

If this does not show a line such as

E: PROXIMITY_NEAR_LEVEL=70

then either try step 2 again (recommended), or try step 3, until udevadm info --export-deb shows that your PROXIMITY_NEAR_LEVEL has been set.

5. Verify your new level with monitor-sensor --proximity . Move your hand near the sensor and it should toggle between 1 (near) and 0 (far).

Taking screenshots

From the command line

There is no key shortcut to take screenshots, but you can use the command line tool grim (sudo apt install grim).

To make one, just call (can easily be done from SSH so that you can see on your phone display what you are screenshotting):

This will save a screenshot in the current directory (if you omit the file name, it will select a unique name automatically).

Unfortunately grim does not support delaying taking a screenshot. In case you want to take a screenshot of something other than the terminal you type grim in - you can run:

to delay the taking of the screenshot by 10 seconds.

GNOME Screenshot

You can install the gnome-screenshot package. Fullscreen screenshots work! Delay timer works fine too, so you can easily change focus to another app or part of the home screen. The 'Window' and 'Selection' options currently cause the app to crash.

To install the package:

Out of the box it will not scale properly on the PinePhone (possibly on other devices too?). To fix this:

Taking screenshots v2 (fancy app)

An even fancier way to take a screenshot using a simple graphical dialog (and initiating it by invoking an "app") has been described here and works flawlessly on Mobian. It is a good combination between convenience and ease of understanding.

Now all you need to do is clicking on the screenshot icon in your app overview. Or issue "screenshot" in the terminal (it might take a relogin to make ~/bin automatically be picked up as PATH).

Taking screenshots v3

(an improved fancy app with correct display in the local language)

Nothing is so good that it can't be even better, in three steps to screenshots in the local language, see there:

#PP_german:matrix.org hopes you have fun creating a screenshot.

Screen recording

If you want to record the screen, you can use the package wf-recorder (sudo apt install wf-recorder).

If you want to make a video grabbing screen and microphone just call (can be done from SSH):

Screen recording v2 (fancy app)

Using the above application wf-recorder in combination with yad and a simple bash-script, one can create a cool GUI for screen recordings (with and without audio recording):

Put this script into /home/mobian/bin/screenrecorder.sh or any similar location:

SCREENCAST="${HOME}/Videos/$(date +%Y-%m-%d-%H%M%S).mp4"

CHOICE=$(yad --title="Screen Recorder" \
    --text="${SCREENCAST}" \
    --window-icon=mpv \
    --button=gtk-ok \
    --form \
    --field="Audio:CHK")

if [[ $? == 0 ]]; then

    AUDIO=$(echo "$CHOICE" | cut -d "|" -f1)

    if [[ "$AUDIO" == "TRUE" ]]; then
        AUDIO_ARG="--audio"
    fi

    wf-recorder $AUDIO_ARG --file="${SCREENCAST}" &
    RECORDER_PID=$!

    yad --title="Screen Recorder" \
        --text="Stop Recording" \
        --button=gtk-cancel

    kill -INT 888 $RECORDER_PID

    notify-send "Screencast" "${SCREENCAST}"

fi

You also need a launcher icon for the script, so put following into /home/mobian/.local/share/applications/screenrecorder.desktop:

[Desktop Entry]
Type=Application
Name=Screenrecorder
Icon=preferences-desktop-screensaver
Exec=/home/mobian/bin/screenrecorder.sh
Terminal=false

Change the path in the Exec= line, if the script has a different location.

Suspend/Sleep

Prevent suspend & keep the screen on

Some applications do not keep the screen on and the screensaver (or suspend) kicks in. (Video players or a long running apt upgrade come to mind). In these case the built-in gnome-session-inhibit tool can be useful. You can use it to run a program and it will inhibit the screensaver and suspend while the program is running. gnome-session-inhibit has various "levels" of inhibiting. Using the --inhibit LEVEL option, it can prevent suspend, or screen blanking/locking with idle (the default).

So, to prevent your phone from going to sleep (but still allow the screen to go blank) while upgrading the system you would run gnome-session-inhibit --inhibit suspend sudo apt upgrade.

It is a nice tweak to add this to your .bashrc file:

# Inhibit suspend when using sudo in a terminal
alias sudo='gnome-session-inhibit sudo'

In order to automate this, you can override certain desktop launchers in /usr/share/applications/*.desktop to wrap the executed command with gnome-session-inhibit.

Prevent suspend via launcher icon

Following script will prevent suspending until you close the application's window.

Put the following script into /home/mobian/bin/prevent-suspend.sh (or any other location...)

gnome-session-inhibit --reason "$(whoami) said so..." \
    --inhibit suspend \
    yad --title "Prevent Suspend" \
        --text "We will NOT sleep, unless you click \"OK\"!" \
        --button=gtk-ok \

echo "OK! Zzzzzzzz"

Make the script that you just created executable:

Also create a launcher icon, by putting the following into /home/mobian/.local/share/applications/prevent-suspend.desktop

[Desktop Entry]
Type=Application
Name=Suspend Inhibitor
Icon=gnome-power-manager
Exec=/home/mobian/bin/prevent-suspend.sh
Terminal=false
X-Purism-FormFactor=Workstation;Mobile;

Change the path in Exec= if your script is at a different location.

Prevent Sleep in an SSH session

Since "inactivity" in the Power settings in Phosh consider only interactions with the screen, it may happen that the device goes into sleep mode while you are accessing it via SSH from another machine. To prevent this, add this little section to the end of your ~/.bashrc:

if [[ -n $SSH_CONNECTION ]]; then
  sh -c "gnome-session-inhibit --inhibit suspend --reason \"SSH connection active\" --inhibit-only > /dev/null 2>&1 &"
fi

This section checks whether the SSH_CONNECTION environment variable is currently set (this is done if you ssh into your phone). If it is, meaning that the current shell is spawned via an SSH session, the code above will use gnome-session-inhibit to prevent the device to suspend/sleep. If the ssh-connection and thus the bash-session is killed, so is gnome-session-inhibit and the device is allowed to suspend again.

Prevent Sleep while media playback is active

A simple Suspend-Guard script can be used to prevent suspending as long as media is playing on the phone (music, video, ...).

The script checks whether any applications is currently outputting audio via the user's PulseAudio or Pipewire PulseAudio server and inhibits suspend for a short amount of time, until it checks again. That way, the phone may suspend as soon as the media is not playing anymore.

The script comes with a handy systemd-unit which enables the guard automatically. You can find the source-code in a user's git-repository. Additions and comments are welcome!

To enable:

git clone https://codeberg.org/jayvii/pinephone-scripts.git
cd pinephone-scripts/sguard
make install
systemctl enable --user sguard --now

Prevent suspend while Wi-Fi Hotspot is active

Combining the knowledge above, this script and desktop entry provides a convenient mechanism to enable the Wi-Fi Hotspot and prevent suspend while active; simply turn the hotspot off and the inhibition will automatically cease: https://desmas.net/mobian/wifi-hotspot-inhibit-suspend/.

It may be necessary to grant permission to the user to control the WiFi Hotspot, which can be done by granting permission to all regular users with an active session like so:

Note: this issue is tracked upstream here

Software updates

Add sid repository

Sid is the unstable debian repository with bleeding edge versions. Modify /etc/apt/sources.list and add this line for the sid repository:

Make sid repository the lowest priority by adding it to /etc/apt/preferences.d/00-mobian-priority. Your file should look like this. The order is important.

Package: *
Pin: release o=Mobian
Pin-Priority: 700

Package: *
Pin: release n=sid
Pin-Priority: 300

Package: *
Pin: release o=Debian
Pin-Priority: 500

Be careful and recall that some of Mobian's packages are patched to work better on a mobile (e.g. GTK) By using sid, you will use a newer version without these adaptations, so your user experience can be worse! Also, Mobian developers test only against the Debian "testing" versions of packages, so you are on your own if you do that.

Upgrade to Bookworm (testing)

Upgrading from bullseye to bookworm won’t be automated and will require editing your sources.list files: simply replace bullseye with bookworm in both /etc/apt/sources.list and /etc/apt/sources.list.d/mobian.list.

Notes:

Please keep in mind that we expect a huge amount of upgrades to be flowing in the weeks following the bullseye release, with plenty of opportunities to break the system, so you might want to wait a bit before upgrading

Once the dust settles, we plan to move more and more of Mobian into the Debian archive with the hope of making Debian bookworm a first-class citizen in the “Linux on mobile” world.

Disable GNOME Software on startup (or hide apps from app drawer)

Copy the .desktop file to the local user override directory with mkdir -p ~/.config/autostart/ && cp /etc/xdg/autostart/org.gnome.Software.desktop ~/.config/autostart/, then edit the new file and add this line to the end: Hidden=true

This can be done for any .desktop file, and if you simply want to hide the icon in the app drawer but keep the startup functionality, add NoDisplay=true to the .desktop file.

Networking

Using SSH with a key instead of password

See Using SSH with a key instead of password

Phone calls

Hints for debugging audio calls are at Mobian/AudioPhoneCallsDebuggingHints. If you only need minor tweaks for phone calls, then see:

Echo cancellation

During a phone call (from caller to callee), the callee may hear his/her voice echoed back. Echo cancellation can, in principle, be handled by hardware or software. As of August 2023, some discussions on echo suppression in Mobian for the PinePhone, PinePhonePro or Librem5 include:

Audio

Auto-connect Devices

You can configure Pipewire to automatically switch the audio output device to any newly connected device, such as a Bluetooth headset or speaker. This just requires loading the module-switch-on-connect module in Pipewire's Pulseaudio server configuration.

Create the ~/.config/pipewire/pipewire-pulse.conf.d/ configuration directory.

mkdir -p ~/.config/pipewire/pipewire-pulse.conf.d/

Now create the file ~/.config/pipewire/pipewire-pulse.conf.d/50-switch-on-connect.conf with the following contents:

pulse.cmd = [
    { cmd = "load-module" args = "module-switch-on-connect" }
]

Restart the Pipewire Pulseaudio server and the Wireplumber session manager.

systemctl --user restart pipewire-pulse.service wireplumber.service

Make the internal speaker louder

Sometimes, it seems like the internal speaker is quiet compared to other phones even though the volume is set to maximum. You can adjust the gain of the "line out" using alsamixer:

sudo apt install alsa-utils
alsamixer

Once the mixer comes up you can use F6 and pick the "PinePhone" device. From there, use the left and right arrow keys to find "Line Out" and then the up arrow to boost the gain of it. You can also boost it a little further by going to "Line Out Source" and picking "Mono Dif" instead of stereo.

Video recording

Currently (as of August 2023) there is no working app to record videos, as pinhole does not seem to work anymore and megapixels doesn't have video recording implemented yet. A simple hack would be to video screen capture the output of megapixels as described above. (November 2023 status of Megapixels for photos: stable and robust for photos on the PinePhone; not yet ready for the PinePhonePro or Librem5)

A summary of additional methods was posted in the forum. All methods are based on an initial reddit post.

The python script doesn't run out of the box anymore and needs further attention, but is a good starting point to play around with currently available options.

Video playback

Clapper

To enable hardware accelerated playback it's recommended to use newer playbin3 element by enabling it in Clapper preferences.

Data import/integration

AndroidImpEx

Development effort for importing contacts from SIM or Contacts/SMS/CallHistory from a rooted Android:

https://gitlab.com/l2385/AndroidImpEx

Download the deb package:

Install with:

Application is able to import from Android:

Contacts from: /data/data/com.android.providers.contacts/databases/contacts2.db
Call History from: /data/data/com.sec.android.provider.logsprovider/databases/logs.db
Messages from: /data/data/com.android.providers.telephony/databases/mmssms.db

The 3 Android databases to be imported should be placed under: /home/mobian/AndroidDBs

Application is also able to import Contacts from SIM

Import and export local address book contacts as VCF or CSV file

The contact app in Mobian uses the evolution-data-service as a backend. As of version 63, gnome-contacts can be used to import and export contacts in vcard format (.vcf).

Export local address book contacts as VCF or CSV file

As of version 43, gnome-contacts can be used to import and export contacts in vcard format (.vcf). Alternatively, the binary addressbook-export located at: /usr/libexec/evolution-data-server can be used to export contacts as CSV or VCF files. In OS versions based in Debian oldstable (e.g: PureOS Amber) the path to this binary is different: /usr/lib/evolution/evolution-data-server/addressbook-export and can be used without having to cd into the directory.

cd /usr/libexec/evolution-data-server && ./addressbook-export --format=csv --output=/home/"$USER"/contacts-backup-"$(date +%Y-%m-%d-%H%M%S)".csv && cd
cd /usr/libexec/evolution-data-server && ./addressbook-export --format=vcard --output=/home/"$USER"/contacts-backup-"$(date +%Y-%m-%d-%H%M%S)".vcf && cd

CalDAV and CardDAV

CalDAV and CardDAV are standards to provide address book and calendar data. You can easily integrate an online CalDAV and CardDAV source when running Nextcloud through the Online Account feature in the settings. This will also make the To-Do app to synchronize your tasks. The data will be synchronized and will even be available when you are online.

If you are not running Nextcloud, you can still integrate CalDAV/CardDAV resources, using this tool: https://gitlab.com/julianfairfax/gnome-dav-proxy. The setup instructions for it can be found here.

Haptic and other feedback

Haptic, visual, or acoustic feedback, by vibrations, an led flashing, or a sound, from events such as receiving an sms are managed by feedbackd. You can, in principle, adjust between full, quiet, or silent profiles for individual software packages with the Mobile Settings gui. As of August 2023, only the silent themes are defined in feedbackd-device-themes. See the upstream README.md file for guides on how to customise this, e.g. by creating a file such as ~/.config/feedbackd/themes/custom.json and using

gsettings get org.sigxcpu.feedbackd theme

and

gsettings set org.sigxcpu.feedbackd theme custom

where custom is the name of your new theme. You should use fbd-theme-validate and fbcli from the feedbackd package to check your themes before and after changes. A faulty custom.json file will cause failures in all the programs that depend on feedbackd, the feedback daemon.

(If the feedback daemon fails to pick up your changes, you might need to restart feedbackd by doing e.g. killall feedbackd and then closing and opening a gui such as chatty that uses feedbackd. Check before and after with ps or top that the daemon is restarted. As of November 2023 in Mobian/trixie, this manual restart should not be needed.)

Other tweaks

Home screen launcher for Voicemail

For certain commonly used phone numbers it's great to have a launcher on the home screen that automatically dials it instead of having to look in contacts, recent calls, etc. It turns out that the calls app supports dialing phone numbers from the command-line and so it is possible to invoke it with a specific phone number from a launcher. Here's an example launcher that you can put in /home/mobian/.local/share/applications/voicemail.desktop.

[Desktop Entry]
Name=Voicemail
StartupWMClass=Voicemail
Comment=Dial voicemail
GenericName=Voicemail
Exec=gnome-calls --dial=<voicemail_phone_number_here>
Icon=/usr/share/icons/hicolor/scalable/actions/mail-inbox-symbolic.svg
Type=Application
Categories=Cell;
MimeType=;
Keywords=Connectivity;

Note that you put whatever your voicemail phone number is in the Exec line. Also, pick the icon that you would like for the launcher or even download a png file somewhere on your phone (e.g. /home/mobian/.local/share/icons) and give that path to it here. Either reboot your phone to see the new launcher or run <code>update-desktop-database /home/mobian/.local/share/applications</code>

Clone partitions form eMMC to microSD or from microSD to eMMC

You can easily clone the eMMC partitions to a microSD card and vice versa as long as the total size of the partitions on the device backup is smaller then the target storage, otherwise you need to resize a partition.

In this example we will clone the eMMC partitions to the microSD, first step listing the eMMC partitions:

# sudo fdisk -l /dev/mmcblk2
Disk /dev/mmcblk2: 14,45 GiB, 15518924800 bytes, 30310400 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0xc4a12776

Device         Boot  Start      End  Sectors  Size Id Type
/dev/mmcblk2p1 *     16384   524287   507904  248M 83 Linux
/dev/mmcblk2p3      524288 29822975 29298688   14G 83 Linux

Two partitions here boot and root, the value that we need is the End sector of the root partition (mmcblk2p3 here), 29822975 that we will use for the count value:

# sudo dd if=/dev/mmcblk2 bs=4096 count=29822975 conv=sync,noerror of=/dev/mmcblk0 status=progress 

Here we just copy all the sectors from mmcblk0 (the eMMC) to mmcblk2 (the microSD). Keep in mind that if you reboot your pinephone with the microSD in, the phone will boot on the microSD and not on the eMMc.

Enabling the display of console output on boot (instead of black screen)

As a default the boot console is the serial interface. You want to also add the terminal. The config is located under /etc/u-boot-menu.d/ and is named after the device used, for example on OG ?PinePhone:

The file should contain the following line (or a similar one):

Remove

Add

in the U_BOOT_PARAMETERS line. Yes, it is twice a "console=" parameter, hopefully to enable two different consoles (serial AND tty1).

The resulting line should look like:

Apply the changes with:

Phosh, Reorder favorites

Phosh favorites are stored as an array of desktop file name in a gsettings entry : <code>/sm/puri/phosh/favorites</code>.

To fetch current favorites array :

After reordering the different element use the following command to set the new favorites order :

Phosh, add an app as mobile friendly in the launcher

Several apps are already mobile friendly but are not categorized as such and therefore do not appear in the Phosh launcher unless you tap on "show all apps".

The method to add an app in the GUI is to open dconf-editor (install it with sudo apt install dconf-editor if you don't have it already). Navigate to <code>/sm/puri/phosh/force-adaptive</code> and toggle off "use default value".

Add the name of the desktop file of the app you want to add as mobile friendly to the list in "Custom value"

Or, if you want to use the terminal, get the default list of mobile friendly apps:

Copy the list of apps in an editor and add the one you want, then apply the change with gsettings set sm.puri.phosh force-adaptive "['your', 'list', 'of', 'mobile-friendly', 'apps']"

It is also possible to get the same result by editing the desktop file for the application under /usr/share/applications, including the line X-Purism-FormFactor=Mobile;

Changing the default username (method 1)

Be warned: Use it right after a fresh flash only! If you have configured apps that are using databases the change will modify database content in a violent way. I would say it is this line of code [grep -rl "$ohp" /$nhp | xargs sed -i "s+$ohp+$nhp+g"]

See also: method 2 below.

To change the current username, you can copy the following section into a text file, make it executable with chmod +x scriptname and run it with sudo ./scriptname.

After the reboot every instance of the username will be replaced with your choice.

# A script to change the current username

set -e

# Get current username
printf "\nType the current username:\n"
read old

# Set desired username
printf "\nType the desired username:\n"
read new

# Home paths
ohp="home/$old"
nhp="home/$new"

# Change username
printf "\nChanging username\n"

for file in group gshadow passwd shadow subgid subuid
do
    sed -i "s/$old/$new/g" /etc/$file*
done

# Rename home folder
mv /$ohp /$nhp

# Fix path references in /home for new user
printf "\nAdjusting paths in home directory\n"

grep -rl "$ohp" /$nhp | xargs sed -i "s+$ohp+$nhp+g"

# Set user info
echo
chfn $new
sync

reboot

If you want to get your hands dirty for educational purposes or you just like to tinker around, you can also follow the instructions below:

This procedure requires ssh unless there is a way to log in as a different user on the phone itself. The main command involved in changing a username requires that all processes running under that user be closed -- as a result, we will need to stop the Phosh process and will lose access to the phone through the touch screen (requiring SSH). First, we will add a temporary user and give it sudo privileges. Although it probably won't matter because we are using ssh, consider only using numbers when creating temp's password.

sudo adduser temp

sudo adduser temp sudo

Don't forget to give the temporary user your ssh credentials if you use public key login.

sudo mkdir /home/temp/.ssh && sudo cp /home/mobian/.ssh/authorized_keys /home/temp/.ssh/authorized_keys

sudo chown -R temp:temp /home/temp/.ssh

Now, exit/logout and log back in as temp through ssh.

Now stop the phosh service.

sudo systemctl stop phosh

Next, run the commands to rename your username, home folder, and group.

sudo usermod -l newusername -m -d /home/newusername oldusername

sudo groupmod -n newusername oldusername

Then modify /etc/dconf/profile/user and replace mobian with your new username.

Run sudo reboot and make sure everything is working. If you have any dotfiles that specify file paths using /home/mobian, you will need to change them. If you were using a custom picture in a directory within /home/mobian as your wallpaper, you will need to set it again.

Finally, you can delete your temporary user:

sudo userdel -r temp

Changing the default username from mobian (method 2)

The default user is mobian. We show here how to change the username. We assume you do not want to conserve any files. See also: method 1 above.

The process is somewhat involved because Phosh is hardcoded to log in automatically to the UID to 1000. This is an opportunity for a volunteer to modify the initial login process to allow the user to enter a preferred username.

If you made it this far, you are able now able to add a new user with UID and GID both being 1000. You may need to reboot twice. If you would like to use sudo from the new user, remember to add yourself to the sudoer group, and consider deleting the root user you made for security. Verify your success by opening a graphical terminal from Phosh. The prompt should be your user@mobian:~$ .

Alternative Desktop Environments

As of November 2023, Phosh is the default desktop environment for Mobian. This does not mean, though, that no alternative environment is available in Debian: here are the instructions to give those a try.

Plasma mobile

On Debian 12 bookworm , a reduced set of Plasma Mobile packages are available: those can be installed with sudo apt update and sudo apt install plasma-mobile plasma-mobile-tweaks plasma-settings plasma-phonebook plasma-dialer spacebar angelfish okular-mobile kscreen.

On Debian trixie and sid, several metapackages are made available to make it easier to try plasma-mobile by installing:

In addition, Mobian provides the mobian-plasma-mobile package to make it even easier, on top of which you should install mobian-plasma-mobile-phone on, well, mobile phones.

You can then select "Plasma Mobile" in the display manager's sessions list.

kde-config-gtk-style

Upon installation of Plasma mobile system, package kde-config-gtk-style is included (unless installing with --no-install-recommends flag), that takes care of changing GTK style settings to have GTK apps appear more pleasant inside Plasma session. This affects the look&feel of Phosh as well, when Phosh session is started after installing Plasma mobile on the system. Most style changes can be reverted with following commands: