Install postmarketOS on your phone for full Linux control
🤖 Researched and drafted automatically from the official docs, and reviewed before publishing. Commands are taken from the source projects — but always sanity-check before running anything on your own hardware.
postmarketOS is a real Linux distribution built for phones and tablets. You get a full package manager, SSH, proper user permissions, and no Google Play Services. It’s not Android—it’s Alpine Linux or Debian on your device. If you want to know exactly what your phone is doing and have the skills to troubleshoot when something breaks, this is the path.
Prerequisites
Before you start, understand what you’re signing up for:
- Device support is limited. postmarketOS runs on a curated list of phones. Check the supported devices list first. If your phone isn’t there, stop here.
- You will lose Android. This is a full replacement. Dual-boot is not standard.
- Hardware expectations. Most supported phones are older flagships or budget models with modest specs. Expect 2–4 GB RAM, aging SoCs. Performance is real but not flagship-smooth.
- Community-driven support. Unlike Android, there’s no corporate QA. You’re relying on volunteer maintainers.
- Keep it off the internet. This is experimental software. Use it on a LAN or behind a VPN, never as your daily driver exposed to untrusted networks.
You’ll need:
- A supported phone (check the device list on the postmarketOS wiki).
- A Linux machine to build and flash the image (a laptop or homelab server running Linux).
- USB cable and a way to enter bootloader/recovery mode on your phone (varies by device).
- Patience. Builds take time, and debugging is manual.
Step 1: Check device support and gather hardware info
Visit the postmarketOS devices wiki and find your phone model. Note down:
- The device codename (e.g.,
samsung-a5,oneplus-enchilada). - The bootloader method (fastboot, heimdall, mtk-tools, etc.).
- Any quirks or missing features listed.
If your device isn’t listed or is marked “not recommended,” reconsider. An unsupported device will not boot.
Step 2: Prepare your Linux build machine
postmarketOS images are built on Linux. You can use a physical machine, VM, or even a homelab server. The build process is CPU-intensive and takes 30 minutes to several hours depending on your hardware.
Install the build dependencies. postmarketOS provides a Docker image for isolated builds, or you can install tools directly.
Using the official approach, clone the postmarketOS repository:
git clone https://github.com/postmarketOS/postmarketOS
cd postmarketOS
Install required tools (varies by distro; check the postmarketOS documentation for your Linux flavor). On Alpine or Debian-based systems, you’ll typically need:
sudo apk add --no-cache git build-base python3 openssl-dev
or
sudo apt-get install -y git build-essential python3 libssl-dev
Step 3: Initialize pmbootstrap
postmarketOS uses pmbootstrap, a Python tool that manages the build environment and device-specific configuration.
Initialize it:
python3 -m pmbootstrap init
You’ll be prompted for:
- Work directory: Where to store build artifacts. Default is fine; use a partition with at least 20 GB free space.
- Device: Enter your device codename (e.g.,
samsung-a5). - Username: A non-root user for the installed system.
- UI: Choose a desktop environment or skip for a minimal CLI system. Common options include Phosh (mobile-friendly GNOME), KDE Plasma Mobile, or none for headless.
- Timezone and locale: Standard setup.
Step 4: Build the rootfs and kernel
Once initialized, build the system image:
python3 -m pmbootstrap build
This compiles the kernel, rootfs, and all packages for your device. It will take a while. The output goes to the work directory.
Step 5: Prepare your phone for flashing
Every device has a different bootloader entry method. Common ones:
For Fastboot devices (most modern):
- Power off the phone.
- Hold Volume Down + Power until you see “Fastboot” or “Bootloader” mode.
- Connect to your build machine via USB.
- Verify the device is detected:
fastboot devices
For Heimdall (Samsung devices):
- Install heimdall on your build machine.
- Power off, then hold Volume Down + Home + Power to enter Download mode.
- Verify detection:
heimdall detect
For other methods (MTK, Qualcomm EDL, etc.): Consult the device-specific wiki page on postmarketOS.
Step 6: Flash the image
postmarketOS provides a flash helper. Run:
python3 -m pmbootstrap flasher flash_kernel
python3 -m pmbootstrap flasher flash_rootfs
For devices using Fastboot directly:
python3 -m pmbootstrap flasher --method fastboot flash_kernel
python3 -m pmbootstrap flasher --method fastboot flash_rootfs
For Heimdall:
python3 -m pmbootstrap flasher --method heimdall flash_kernel
python3 -m pmbootstrap flasher --method heimdall flash_rootfs
Do not interrupt the process. Once complete, the phone will reboot into postmarketOS.
Step 7: First boot and initial setup
The first boot takes a minute or two. You’ll see a black screen, then a login prompt or graphical UI depending on what you chose during init.
If you selected a UI (Phosh, KDE Plasma Mobile), it will launch. If headless, you’ll get a text login. Log in with the username you set during initialization.
Update packages:
sudo apk update
sudo apk upgrade
Or on Debian-based postmarketOS variants:
sudo apt-get update
sudo apt-get upgrade
Step 8: Install and configure essentials
postmarketOS is barebones by design. Add what you need.
SSH server (to manage the phone remotely):
sudo apk add openssh
sudo rc-service sshd start
sudo rc-update add sshd
Networking tools:
sudo apk add curl wget htop
Mobile-friendly terminal (if using a UI):
sudo apk add xterm
Matrix/Signal client (for secure messaging):
postmarketOS has community packages. Search the repository:
apk search signal
apk search matrix
Install what’s available. Note: app availability is limited compared to Android.
Step 9: Network and connectivity
Wi-Fi and cellular support depend on your device. postmarketOS uses standard Linux networking tools.
For Wi-Fi:
sudo apk add wpa_supplicant
Configure via /etc/network/interfaces or use a network manager if one is installed with your UI.
For cellular (modem):
If your device has modem support, postmarketOS includes ofono or ModemManager. Check the device wiki for status. Cellular is often incomplete on older devices.
Step 10: Harden and maintain
- Keep packages updated: Run
apk upgradeorapt-get upgradeweekly. - Use a firewall: Install
ufwornftablesif you plan to expose services. - Disable unnecessary services: Check running services with
rc-service -land disable what you don’t need. - SSH key auth only: Disable password login on SSH if you enable it.
- Backups: postmarketOS images can be rebuilt from source, but back up your
/homedirectory to your build machine.
Troubleshooting
Phone won’t boot after flashing:
- Reflash the image. Make sure your device was in the correct bootloader mode.
- Check the device wiki for known issues.
- Try a different UI or go headless.
No Wi-Fi or cellular:
- Check device support. Some devices lack working drivers.
- Install
iwandipto debug:
iw dev
ip link
Performance is sluggish:
- postmarketOS on older hardware is inherently slower. Close unnecessary apps and background services.
- Consider a headless setup if you don’t need a UI.
Can’t connect via SSH:
- Ensure sshd is running:
sudo rc-service sshd status. - Check your phone’s IP:
ip addr show. - Verify firewall rules aren’t blocking port 22.
Is it worth it?
Yes, if you want a phone you actually control and understand. You’ll have full access to the filesystem, can audit what’s running, and can customize everything. No Google, no Samsung bloat, no mysterious background services.
No, if you need a daily driver. App ecosystem is thin, hardware support is spotty, and you’ll spend time debugging. postmarketOS is for tinkerers, not for people who want things to “just work.”
Run it behind a VPN or on a trusted LAN only. This is experimental software. Treat it like a homelab project, not a hardened production device.
Sources
Related video
New self-hosted AI & homelab shorts, daily.
Subscribe on YouTubeRelated guides
Turn an old webcam into an AI security camera with Frigate
Run Frigate NVR on a spare PC to detect people, cars, and animals in real-time from cheap IP cameras or old USB webcams. Local processing, no cloud, integrates with Home Assistant.
Turn a $15 Android TV Box into an Armbian Linux Server
Flash Armbian on Amlogic S905/S922 TV boxes to run Docker, Pi-hole, and other services. Boot from USB first—eMMC flashing can brick it.
Turn an Old Laptop into a Home Server with CasaOS
Install CasaOS on Debian/Ubuntu with one command and get a click-install app store for Jellyfin, Nextcloud, Home Assistant. Runs on x86 and ARM.