Quick start

Four steps from Android apps to an installed desktop and renderer check. Download time varies with the device, mirrors and network.

Step 1 — Install two apps

Termux — the host terminal. Download the APK from GitHub releases or F-Droid. This guide uses the main F-Droid/GitHub release line. The Google Play line is separate and experimental; do not mix Termux/plugin sources.
Termux:X11 — the app that displays the desktop. Download from GitHub releases. Open it once so Android registers it, then leave it.

Step 2 — Run the installer

Open Termux and paste:

curl -fsSL https://soobujmiah.github.io/ternux/install.sh | bash

curl broken after an upgrade? Use wget — same installer:

wget -qO- https://soobujmiah.github.io/ternux/install.sh | bash

The installer:

checks the device (architecture, Android version, storage, network);
installs the Termux packages (X11, PulseAudio, PRoot);
installs Debian + Xfce4 inside a PRoot container;
detects your GPU and picks the right driver (Adreno → Zink/Turnip · other → VirGL);
configures audio, fonts and locale;
writes the x launcher and shell shortcuts;
verifies everything landed.

Expect about 3–4 GB installed for base or 10–12 GB with --all; keep additional temporary space for downloads and caches. One persistent screen shows the device panel, step progress and a live log window until the final status; a terminal that cannot host it gets a plain framed log instead. Both record the complete output — see The installer screen.

Prefer to review all code before it runs? Clone the repository; reviewing only the bootstrap is incomplete because it otherwise downloads library modules at runtime.

pkg install git -y
git clone https://github.com/soobujmiah/ternux.git
cd ternux
git log -1 --oneline
(set -e; for f in install.sh uninstall.sh bin/ternux bin/ternux-guest lib/*.sh; do bash -n "$f"; done)
less install.sh bin/ternux bin/ternux-guest lib/*.sh
bash install.sh

Step 3 — Start the desktop

source ~/.bashrc

The x shortcut launches: audio bridge → display (Termux:X11) → Debian → Xfce4. Switch to the Termux:X11 app — your desktop is there.

Step 4 — Verify the renderer

Open a terminal inside the desktop (right-click → Open Terminal Here):

glxinfo | grep "renderer string"

Expected	Meaning
`zink Vulkan (Adreno (TM) … (MESA_TURNIP))`	✅ hardware GPU path (Adreno)
`virgl` / `virpipe` without `llvmpipe`	✅ VirGL compatibility path is active; performance varies
`llvmpipe`	❌ CPU software rendering — troubleshoot before benchmarking

If you see llvmpipe, the desktop still works but graphics are software-only. Jump to Troubleshooting → renderer says llvmpipe.

What you now have

Classic shell shortcuts

x          start the desktop          killx   stop everything cleanly
db         shell inside Debian (user) droot   shell as root
xgo        auto-open Termux:X11 + x   sysmon  device resource overview
clean-mesa clear the Mesa shader cache

Ternux CLI — the management interface

After installation, the ternux command is your permanent control centre. Run the full commands below in Termux ($PREFIX/bin/ternux):

ternux doctor           # system diagnostics
ternux start            # start the desktop
ternux stop             # stop the desktop
ternux repair           # auto-fix common issues
ternux verify           # verify installation
ternux benchmark        # GPU benchmarks
ternux info             # system information
ternux update           # self-update
ternux uninstall        # remove components

Inside the Debian/Xfce terminal, /usr/local/bin/ternux provides guest-local status, info, doctor, and env. It rejects host lifecycle commands to prevent nested PRoot; return to Termux for start, stop, repair, or update.

The dispatcher recognizes global flags including --help, --json, --verbose, and --quiet, but structured output is command-specific. Use --json only where it is documented in the CLI Reference.

A full Debian desktop in a PRoot userland on the phone’s native ARM64 CPU.
A configured Zink/Turnip or VirGL graphics route for OpenGL apps; verify the actual renderer rather than assuming acceleration.
Sound bridged to the phone speakers/headphones.
Shared storage between Android and Debian (~/storage in Termux ↔ /sdcard inside the container).

Android 12+? One important note

Android 12+ child-process policy can terminate PRoot processes, while memory pressure and OEM battery management can look identical. The installer reports readable settings and links version-aware guidance; review the system-wide trade-off before changing a safeguard. Full details in Troubleshooting.

Installation — every phase explained, all options, uninstall
Manual installation — every command by hand, both GPU routes
Usage — Blender, local AI, development, backups
FAQ — safety, storage, battery, gaming