PostmarketOS with Plasma Mobile

How to Install PostmarketOS with Plasma Mobile in Termux (ZINK GPU Accelerated)

This guide demonstrates how to install and run postmarketOS v22.06 (based on Alpine Linux v3.16) inside Termux using proot-distro. This configuration represents a sweet spot for running Plasma Mobile desktop environment with hardware acceleration via Termux-X11 and ZINK drivers.

Note: Newer Alpine versions (v3.17+) drop support for legacy X11 sessions in favor of Wayland, making v22.06 the recommended choice for X11-based PRoot setups. Plasma Mobile seamlessly supports both portrait and landscape screen orientations.

---

Prerequisites & Requirements

Before proceeding, ensure you have the following installed on your Android device:

• Termux & Termux-X11 companion app installed.
• proot-distro package installed in Termux.
• PulseAudio audio server enabled in Termux.

If you haven’t configured Termux-X11 and Audio yet, follow this base setup guide on Reddit first.

---

Step-by-Step Installation Guide

Step 1: Install Alpine Linux Base

Open Termux and run the following command to download the base Alpine container:

pd install alpine

Step 2: Log into Alpine PRoot Environment

pd sh alpine

---

Step 3: Add postmarketOS Repositories

Open the Alpine repository configuration file using nano:

nano /etc/apk/repositories

Add the following postmarketOS v22.06 mirror link to the file:

https://mirror.postmarketos.org/postmarketos/v22.06

Save and exit (Press Ctrl + X, then Y, then Enter).

Next, pin your repositories to Alpine v3.16 instead of the edge branch:

sed -i 's/edge/v3.16/g' /etc/apk/repositories

---

Step 4: System Upgrade & User Setup

Update packages, install system administration tools, and create a non-root user:

clear
apk update && apk upgrade
apk add nano sudo neofetch alpine-conf
addgroup storage
addgroup power
addgroup network
adduser -g wheel,audio,video,power,storage,lp,sys,network user

CRITICAL WARNING: When prompted to set a user password, use digits/numbers ONLY (e.g., 1234). Using letters or special characters will cause authentication to fail on login inside PRoot.

Grant administrative privileges to the new user and install Plasma Mobile dependencies:

echo "user ALL=(ALL:ALL) NOPASSWD:ALL" > /etc/sudoers
su user -c "sudo setup-xorg-base postmarketos-ui-plasma-mobile maliit-keyboard"
exit

---

Step 5: Fix OS Release Identification

Update system identity files so neofetch and desktop apps properly identify the OS as postmarketOS:

rm -f /etc/os-release
nano /etc/os-release

Paste the following configuration into the editor:

PRETTY_NAME="postmarketOS v22.06"
NAME="postmarketOS"
VERSION_ID="v22.06"
VERSION="v22.06"
ID="postmarketos"
ID_LIKE="alpine"
HOME_URL="https://www.postmarketos.org/"
SUPPORT_URL="https://gitlab.com/postmarketOS"
BUG_REPORT_URL="https://gitlab.com/postmarketOS/pmaports/issues"
LOGO="postmarketos-logo"

Save and exit the file.

---

Step 6: Create the Startup Launcher Script

Exit the Alpine shell to return back to the main Termux environment:

exit

Create a dedicated boot script named alpinepm.sh:

nano alpinepm.sh

Paste the full launcher script below:

#!/data/data/com.termux/files/usr/bin/bash

# Kill previous display and audio instances
killall pulseaudio 2>/dev/null
killall virgl_test_server 2>/dev/null

# Set ZINK MESA acceleration flags
MESA_LOADER_DRIVER_OVERRIDE=zink \
GALLIUM_DRIVER=zink \
ZINK_DESCRIPTORS=lazy \
virgl_test_server --use-egl-surfaceless &

kill -9 $(pgrep -f "termux.x11") 2>/dev/null

# Start PulseAudio server
pulseaudio --start
export XDG_RUNTIME_DIR=${TMPDIR}

# Launch Termux-X11 server
termux-x11 :0 >/dev/null &
sleep 3

# Trigger Termux-X11 Android app activity
am start --user 0 -n com.termux.x11/com.termux.x11.MainActivity >/dev/null 2>&1
sleep 1

# Boot into postmarketOS Plasma Mobile session
proot-distro login alpine \
--user user \
--isolated \
--shared-tmp -- \
/bin/bash -c '
export PULSE_SERVER=127.0.0.1
export DISPLAY=:0
export MESA_GL_VERSION_OVERRIDE=4.6
export GALLIUM_DRIVER=zink
dbus-launch startplasma-x11
'

exit 0

Grant executable permissions to the script:

chmod +x alpinepm.sh

---

Step 7: Install ZINK GPU Acceleration (Termux Side)

Install Mesa ZINK drivers inside Termux for hardware-accelerated 3D rendering:

pkg install mesa-zink virglrenderer-mesa-zink

---

Step 8: Launch Plasma Mobile

Run the boot script to start the desktop environment:

./alpinepm.sh

To end the desktop session, press Ctrl + C in the main Termux terminal window or swipe to force close Termux.

---

Troubleshooting & Performance Notes

• Orientation: Plasma Mobile dynamically adjusts layout depending on whether your device is in portrait or landscape mode.
• Audio Output: Ensure PulseAudio daemon is granted background execution permissions on your Android device settings.
• Performance: Performance will depend on your mobile GPU's Vulkan capabilities, as ZINK translates OpenGL calls directly to Vulkan.