homelabprivacy

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):

  1. Power off the phone.
  2. Hold Volume Down + Power until you see “Fastboot” or “Bootloader” mode.
  3. Connect to your build machine via USB.
  4. Verify the device is detected:
fastboot devices

For Heimdall (Samsung devices):

  1. Install heimdall on your build machine.
  2. Power off, then hold Volume Down + Home + Power to enter Download mode.
  3. 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 upgrade or apt-get upgrade weekly.
  • Use a firewall: Install ufw or nftables if you plan to expose services.
  • Disable unnecessary services: Check running services with rc-service -l and 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 /home directory 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 iw and ip to 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.

Related video

New self-hosted AI & homelab shorts, daily.

Subscribe on YouTube

Related guides

← All guides