linux-android: a Termux script that turns an old phone into a GPU-accelerated Linux desktop or a Home Assistant hub
Turn an old Android phone into a GPU-accelerated Linux desktop (XFCE4 / KDE Plasma / LXQt / MATE) or a Home Assistant smart home server — using Termux. No root, no PC, no cloud.
At a glance
- What is it?
- Two shell scripts, no root and no PC. The repository targets arm64 phones with 3 GB of RAM or more, and leans on Turnip plus Zink for Adreno GPUs. It is a guided installer for people who want a desktop on hardware Android abandoned, not a general-purpose Linux-on-Android toolkit.
- Who is it for?
- Adopt it if you have an arm64 phone with 3 GB or more of RAM, a Snapdragon chip, and you want XFCE4 or LXQt on a screen rather than a tiling setup you assemble yourself. Do not use it on a 2 GB device, on a 32-bit phone, or if you expect a general-purpose distro manager: the script hardcodes one desktop per run and its GPU fallback on Mali is software Vulkan.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 20 days ago.
- What is it written in?
- Mainly Shell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem is a drawer full of phones that still boot
An old Android phone is a screen, a battery, an arm64 SoC and 3 to 6 GB of RAM sitting in a drawer because the vendor stopped shipping updates. It cannot run a current Android release, but it is not broken hardware. linux-android exists to convert that hardware into something you can log into: a Linux desktop with Firefox, VLC, Python, OpenSSH and optional Wine, or a Home Assistant Core instance that controls Wi-Fi lights and plugs. The README frames the audience directly with a two-column table, one path for a GUI desktop, one for a smart home hub, and notes that both can run on the same phone because they do not conflict. That is the whole pitch. It is aimed at people who want to learn Linux, run a small SSH server, host a dashboard, or do Python work on a device they already own, and who are willing to accept a phone-shaped computer as the trade. It is not aimed at anyone who needs a supported operating system with security updates, and the README does not pretend otherwise.
What the scripts actually do: proot-distro, Termux-X11 and a GPU profile file
The repository is Shell, with two entry points named in the README: termux-linux-setup.sh and setup-homeassistant.sh. The desktop path installs through Termux and Termux-X11, the Android app that acts as the display server and renders the desktop on screen. Inside Termux, the stack listed under What Gets Installed is Termux-X11 for display, a desktop environment of your choice, Mesa and Zink for OpenGL over Vulkan, the Turnip driver when a Qualcomm Adreno GPU is detected, D-Bus because every desktop's settings daemon needs a session message bus, PulseAudio for sound, plus Firefox, VLC, Git, wget, curl, Python 3 with pip, and OpenSSH. Wine is optional and the README describes it as running Windows x86 applications through Hangover and Box64. The topics list names proot-distro, which is the mechanism that gives you a Linux userland without root. The GPU decision is written to a file, ~/.config/linux-gpu.sh, and start-linux.sh loads it on every launch. That file is the control surface: the README says you can edit it to tweak Mesa flags, which means the acceleration setup is inspectable rather than buried in the installer. Detection is done through hardware properties rather than the brand name, and the README gives a concrete reason: Samsung ships both Adreno and Mali phones depending on region, so brand detection would be wrong on some devices.
Getting it running: four commands and one app you must not install from the Play Store
The prerequisites are two apps. Termux must come from F-Droid, and the README is explicit that the Play Store build is outdated. Termux-X11 comes from its GitHub releases as an .apk. Hardware requirements are an arm64 processor, 3 GB of RAM recommended and 4 GB or more for KDE Plasma, and 5 to 10 GB of free storage, more if Wine is involved. The first Termux commands are termux-wake-lock followed by pkg upgrade -y. Both matter. The README states that termux-wake-lock keeps Termux alive when the screen turns off, and that without it Android can kill the process mid-install. The upgrade is described as preventing a known crash involving libpcre and libandroid-selinux. Then the script itself: curl -O the raw URL from the main branch, chmod +x, and bash termux-linux-setup.sh. It prompts for a desktop environment and for Wine, and does the rest automatically, with a full log written to ~/termux-setup.log. Starting the desktop is bash ~/start-linux.sh followed by opening the Termux-X11 app, and stopping it is bash ~/stop-linux.sh. The README quotes 10 to 30 minutes for the desktop path and 15 to 45 minutes for Home Assistant, both dependent on connection speed. The SSH instructions specify opening a terminal in Termux itself rather than inside the desktop, which is the kind of detail that saves an afternoon.
The GPU story is the interesting part, and the fallback is honest
On a Qualcomm Adreno phone the script installs the open-source Turnip Vulkan driver and runs OpenGL through Zink, which the README describes as near-native GPU performance. On Mali or other GPUs it falls back to Zink plus SwRast, which is software Vulkan, and the README states plainly that this is functional but lighter, recommending XFCE4 or LXQt in that case. The packaging detail is worth reading twice. Zink ships in Termux's own mesa package at $PREFIX/lib/dri/zink_dri.so and has done so since Mesa 23. The script only reaches for the third-party mesa-zink build when the installed Mesa genuinely lacks Zink, or when mesa-zink is already present from an earlier run, because the two stacks ship the same library filenames and cannot be mixed. That is a real constraint and the README treats it as one. Verification is left to the user, with two commands to run from a terminal inside the desktop: vulkaninfo --summary piped through head -30 to see which Vulkan driver the loader picked, and glxinfo -B filtered for renderer and OpenGL version, where the renderer should say zink. Those two commands are the only way to know which path you landed on.
Limits: arm64 only, one desktop per run, and no security updates
The hardware floor rules out a lot of the phones people actually have in drawers. A 32-bit device is out. A 2 GB phone is out for anything except LXQt, which the README lists as very low resource usage and recommends for 2 to 3 GB devices, and even then the 3 GB recommendation is the stated baseline. KDE Plasma is called high usage and restricted to powerful phones. The script installs one desktop environment per run, chosen at the prompt, so switching from XFCE4 to MATE means running the installer again rather than adding a session. Wine is the largest storage consumer, pushing past the 5 to 10 GB range. The deeper limitation is not in the README at all: this is Android underneath, with Android's kernel and Android's update situation, and Termux is a userland running on top of it. Nothing here changes the fact that the base system stopped receiving patches when the vendor stopped shipping them. The README also points out that the accompanying video was recorded on LineageOS on a OnePlus 5T while stating the script works on stock Android, so the demonstration environment is not identical to the default one. Anyone reading the video as a stock-Android reference should adjust expectations.
Against a plain Termux plus proot-distro setup
The obvious alternative is doing it by hand: install Termux from F-Droid, install proot-distro, install a distribution, install Termux-X11, and wire up the display, audio and D-Bus yourself. That path is more flexible. You choose the distribution, you choose when to upgrade it, and you can add or remove desktop environments without rerunning an installer. It also takes considerably longer and requires you to solve the parts linux-android has already solved: the wake lock before a long install, the libpcre and libandroid-selinux crash, the session bus that desktop settings daemons expect, and the Zink versus mesa-zink filename collision. The difference in approach is that linux-android makes those decisions for you and records the GPU result in one editable file, while a manual setup leaves every decision open and every failure mode yours to diagnose. If you already know how to assemble Termux-X11 and proot-distro, the script saves you the setup and costs you the flexibility. If you do not, the script is the difference between a working desktop and an evening of reading error logs.
Maintenance, licensing and what the repository does not tell you
The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive arrangement and it places no copyleft obligation on anything you build around it, but it also means the author carries no warranty, and this is a script that modifies your Termux environment and installs a distribution. Read LICENSE for the exact terms rather than treating this summary as legal advice. On maintenance, the material supports only a few statements: the default branch is main, the last push recorded is 2026-08-26, the repository is not archived, and no releases were retrieved, so there is no tagged version to pin to and no changelog to read between runs. The README describes the install log at ~/termux-setup.log as the place to look when something goes wrong, and the GPU profile at ~/.config/linux-gpu.sh as the file to edit when you want to change Mesa flags. Those two files are the practical maintenance surface. The script pulls packages from Termux repositories at install time, so what you get depends on the state of those repositories on the day you run it, not on a frozen snapshot in this repository. Re-running the installer later is a different operation from re-running it today, and the README does not document an upgrade path beyond that.
Editorial conclusion
Adopt it if you have an arm64 phone with 3 GB or more of RAM, a Snapdragon chip, and you want XFCE4 or LXQt on a screen rather than a tiling setup you assemble yourself. Do not use it on a 2 GB device, on a 32-bit phone, or if you expect a general-purpose distro manager: the script hardcodes one desktop per run and its GPU fallback on Mali is software Vulkan. Before committing, run vulkaninfo --summary and glxinfo -B inside the desktop and confirm the renderer line says zink; if it does not, the desktop you get is the SwRast path and the machine will feel it.
Community notes