mayukh4/linux-android: a Termux script that turns an old Android phone into a Linux desktop

The problem: a drawer phone with a working SoC

An old Snapdragon phone is a small computer with a battery, a screen, Wi-Fi, and a GPU that still outperforms most single-board computers at the same price. The reason it sits in a drawer is software, not silicon. Android gives you no package manager you would want to develop against, no X11 or Wayland session, and no desktop browser. Flashing a custom ROM is the usual answer, and it costs an unlocked bootloader, a wipe, and an evening of risk.

This project takes the other route. It stays inside stock Android and uses Termux as the substrate, then layers a proot-based Linux userland on top. The stated audience is people who want to learn Linux, run Python, host an SSH endpoint, browse the web with a real browser, or stand up a Home Assistant hub, without rooting the device. The README is explicit that the script works on stock Android and that the accompanying video happens to demonstrate LineageOS on a OnePlus 5T; root is not a requirement of the script itself. That framing matters, because it puts the project in the same category as proot-distro setups rather than in the custom-ROM category, and the constraints that follow are different.

What the scripts actually install, and how the pieces connect

There are two entry points at the repository root: termux-linux-setup.sh and setup-homeassistant.sh. They are independent, and the README states you can run both on the same phone without conflict.

The desktop path composes four layers. Termux-X11 is the display server, an Android app that renders an X session on the phone screen. Inside Termux, the script installs a desktop environment of your choice (XFCE4 is the default, with LXQt, MATE and KDE Plasma as alternatives), D-Bus for the session message bus that desktop settings daemons expect, PulseAudio for audio, and Mesa. Mesa is where the graphics story lives: the script relies on Zink, the OpenGL-on-Vulkan translation layer, so that OpenGL applications are executed against a Vulkan driver. On Qualcomm Adreno hardware the Vulkan driver is Turnip, the open-source Adreno driver, which is why the README describes near-native GPU performance on Snapdragon phones. On Mali and other GPUs there is no equivalent open Vulkan driver in this stack, so the fallback is Zink plus SwRast, a software Vulkan implementation. The README recommends lighter desktops in that case, and that recommendation is not cosmetic: a compositing KDE session on software Vulkan will be slow in a way that no amount of configuration fixes.

One detail in the README is worth reading twice. Zink ships inside Termux's own mesa package at $PREFIX/lib/dri/zink_dri.so, and has done so since Mesa 23. The script only falls back to the third-party mesa-zink build when the installed Mesa genuinely lacks Zink, or when an earlier run already left mesa-zink in place. The reason given is that the two stacks ship the same library filenames and cannot be mixed. That is a real constraint, not a footnote, because it means an interrupted or partial prior install can leave a phone in a state where the graphics stack is a blend of two providers.

GPU detection is done by hardware properties rather than brand name. The README explains the reasoning: Samsung ships both Adreno and Mali phones depending on region, so brand detection is unreliable. The resulting environment is written to ~/.config/linux-gpu.sh and sourced on every start-linux.sh, which gives you a single file to edit if you want to change Mesa flags.

Installing it and getting to a first desktop

The prerequisites are two apps. Termux comes from F-Droid, and the README says plainly not to use the Play Store version because it is outdated. Termux-X11 comes from its GitHub releases page as an .apk. Both need whatever permissions they request.

Before running anything else, the README asks you to pre-upgrade Termux. The wake lock is not a nicety: without it Android can kill the Termux process while the install is running and the screen is off.

termux-wake-lock
pkg upgrade -y

The upgrade is described as preventing a known crash involving libpcre and libandroid-selinux, so skipping it to save a few minutes is a bad trade.

With that done, fetch the script and run it. It prompts for a desktop environment and for whether you want Wine, and handles the rest.

curl -O https://raw.githubusercontent.com/mayukh4/linux-android/main/termux-linux-setup.sh
chmod +x termux-linux-setup.sh
bash termux-linux-setup.sh

Expect 10 to 30 minutes depending on connection speed. A full log is written to ~/termux-setup.log, and that file is the first place to look when a step fails.

Starting and stopping the session is a pair of generated scripts. After running the start script, you switch to the Termux-X11 app to see the desktop.

bash ~/start-linux.sh

bash ~/stop-linux.sh

Once inside, two commands tell you what the graphics stack actually resolved to. The README gives both, and they are the only way to confirm you got the path you expected rather than the software fallback.

vulkaninfo --summary | head -30
glxinfo -B | grep -i "renderer\|opengl version"

The renderer line should say zink. If it does not, the Turnip driver was not picked up and you are on SwRast.

Where this breaks: rootless constraints and the Mali tax

The honest limitation is the GPU split, and the README does not hide it. Adreno phones get Turnip plus Zink. Everything else gets Zink plus SwRast, described as functional but lighter. In practice that means a phone with a Mali GPU can run XFCE4 or LXQt acceptably and should not be asked to run KDE Plasma, regardless of how much RAM it has. If you are shopping for a cheap used phone specifically for this, the SoC matters more than the RAM figure.

The second limitation is the absence of root. Nothing here changes the kernel, so you inherit Android's process management. The wake lock exists precisely because the OS will reclaim Termux when the screen is off, and that behaviour does not disappear after installation. A long build or a large download needs the lock held. The README does not document a rollback procedure, and there is no uninstall script in the repository listing; removing the setup means deleting the Termux data yourself, which also takes out anything else you had in Termux.

Wine is the third soft spot. The README lists it as optional and describes running Windows x86 applications via Hangover plus Box64. That is a translation chain with two layers of emulation in it, and the README does not publish compatibility figures or a list of known-working applications. Treat Wine here as an experiment, not as a reason to choose this project.

Finally, hardware floors are real. arm64 is required, 3 GB of RAM is the recommendation, 4 GB for KDE Plasma, and 5 to 10 GB of free storage before Wine. A 2 GB phone is outside the supported range.

How this differs from proot-distro and from a custom ROM

The closest comparison is proot-distro itself, which is the mechanism this project wraps. proot-distro gives you a rootfs and a shell; it does not choose a desktop environment, wire up Termux-X11, configure D-Bus and PulseAudio, detect your GPU, or write start and stop scripts. The difference is the difference between a tool and an opinionated setup: you get a working desktop in one run, and you give up the flexibility of assembling the stack yourself. If you already know which Mesa flags you want, proot-distro plus manual configuration is the more direct path.

The other comparison is a custom ROM with a real Linux userland, or a device like a PinePhone. Those give you actual root, a mainline kernel, and no Android process manager killing your session. They cost you the phone you already own. This project's entire value proposition is that it runs on the hardware in your drawer with no flashing, and every limitation above follows from that single choice.

For the Home Assistant path, the alternative is a Raspberry Pi. The Pi gives you a supported, well-documented host with predictable storage and no wake-lock problem. The phone gives you a free one with a built-in battery, which is a genuinely useful property for a hub during a power cut, and a less predictable thermal and storage profile.

Maintenance, licence and what upgrades cost you

The repository is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the whole of the licence implication here, and it is a permissive one; nothing in the README adds terms on top. The README also credits third-party components with their own licences, notably the Turnip driver, Mesa and Home Assistant, and those obligations travel with whatever you redistribute.

The last push to the repository was on 2026-08-26, so this is a recent codebase rather than an abandoned one, but there are no retrieved releases, which means there is no tagged version to pin to. Upgrades therefore mean re-running the script from main or pulling the file again, and the README's own warning about not mixing the two Zink providers is the concrete risk in doing that. If a future run decides your Mesa lacks Zink and installs mesa-zink over a tree that already has the Termux-provided library, you have the mixed state the README warns about. Keep the ~/termux-setup.log from a working install, because it is the only record of which branch the script took on your device.

Editorial conclusion

Adopt it if you have an arm64 phone with 3 GB or more of RAM, a Snapdragon chip, and a willingness to read ~/termux-setup.log when a step fails. Skip it if you need a supported product with a rollback path, if your phone is 32-bit or has 2 GB of RAM, or if you want an x86 desktop workload that Wine plus Box64 cannot realistically carry. Before you commit an evening, verify three things: that your SoC is Adreno rather than Mali, that you installed Termux from F-Droid and not the Play Store, and that `glxinfo -B` inside the desktop reports zink as the renderer. If that last check prints SwRast, you are on the software path and should plan around XFCE4 or LXQt rather than KDE Plasma.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mayukh4/linux-android on GitHub
4. Project website
5. README