Linux on Android is a fully automated script that installs, configures, and manages full Linux distributions inside Termux using proot-distro, all without requiring root access.
This tool makes Linux‑on‑Android setups:
- Reproducible
- Beginner‑friendly
- Frictionless
- Safe
- Perfect for repurposing old devices
Use it to turn any Android phone or tablet into:
- A lightweight Linux server
- A portable development machine
- A learning environment
- An automation node
- A personal experimentation sandbox
No aliases. No manual steps. No guesswork.
👉 Prefer manual installation?
Check out the Manual Installation Guide.
No interactive prompts inside the distro, everything is handled cleanly.
Install a GUI with one choice.
VNC is configured automatically with a working xstartup.
Fixes the common Cannot start VNC:1 issue by removing stale lock files.
Creates a non‑root user with passwordless sudo via /etc/sudoers.d.
Remove one distro or wipe all distros + configs.
You control how you start/stop VNC and how you log in.
- Android 8.0+
- Termux (F‑Droid recommended)
- 4–6 GB free storage
- Internet connection
- Optional: VNC viewer (RealVNC, bVNC, etc.)
-
Install Termux from F‑Droid:
https://f-droid.org/packages/com.termux/ -
Update Termux and install Git:
apt update && apt upgrade -y apt install git -y -
Clone the repository:
git clone https://github.com/uzairmukadam/linux-on-android.git cd linux-on-android -
Make the script executable:
chmod +x linux-on-android.sh
-
Run the script:
./linux-on-android.sh
-
Follow the on‑screen prompts.
Supports any distro available through proot-distro.
Passwordless login, safe sudo access.
If selected, the script installs:
- LXDE
- TightVNCServer
- A working
xstartup - A VNC password
- Automatic lock‑file cleanup
- A test VNC session to initialize configs
Each installed distro gets a config file in:
$PREFIX/etc/linux-on-android/<distro>.conf
Remove one distro or all of them.
proot-distro login <distro> --su - <username>vncserver -geometry 1920x1080 :1vncserver -kill :1localhost:5901
Password: 1234 (default)
vncserver -kill :1exitexitFrom Termux:
pkill -9 -f prootexitThen swipe Termux away from recent apps.
./linux-on-android.shChoose: Uninstall a specific distro
Choose: Uninstall ALL distros
You can also optionally remove proot-distro.
Any distro supported by proot-distro, including:
- Debian
- Ubuntu
- Arch Linux
- Fedora
- Alpine
- Void Linux
- No GPU acceleration (Android does not expose GPU to proot)
- No systemd
- VNC performance depends on device hardware
- Some desktop apps may require additional packages
Most proot-distro rootfs images are intentionally minimal. They include only the bare essentials needed to boot a userspace environment. This keeps downloads small, reduces storage usage, and speeds up installation — but it also means many common tools are not included by default.
It’s normal for the following to be missing:
-
Editors (
nano,vim,micro) -
Build tools (
make,gcc,cmake,pkg-config) -
Networking utilities (
curl,wget,net-tools) -
Compression tools (
zip,unzip,tar,xz-utils) -
GUI components (if you didn’t install a desktop environment)
You can install any of these manually using your distro’s package manager.
Use your distro’s package manager:
-
Debian/Ubuntu:
sudo apt install <package> -
Arch Linux:
sudo pacman -S <package> -
Alpine:
sudo apk add <package> -
Fedora:
sudo dnf install <package> -
Void Linux:
sudo xbps-install <package>
This usually means one of the following:
-
Your rootfs image is extremely minimal
-
Your package lists are outdated
-
Optional repositories (like “community”, “extra”, “contrib”, or “nonfree”) are disabled
-
The package isn’t available for your architecture (ARM vs ARM64 vs x86_64)
Updating your package lists or enabling additional repositories typically fixes this.
Here are official resources for each major distro supported by proot-distro:
-
Debian/Ubuntu: https://wiki.debian.org/Apt
-
Arch Linux: https://wiki.archlinux.org/title/Pacman
-
Alpine: https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management
-
Fedora: https://docs.fedoraproject.org/en-US/quick-docs/dnf/
-
Void Linux: https://docs.voidlinux.org/xbps/index.html
These pages explain how to enable extra repositories, install missing tools, and troubleshoot package issues.
No. proot runs in userspace and cannot access kernel‑level hardware like GPU, DRM, or kernel modules.
proot does not support PID 1 or kernel‑level init systems. Use supervisord or run services manually.
su - loads a full login environment (PATH, HOME, DBus, configs).
su does not, and it breaks desktops and VNC.
This usually means an LXDE component failed to attach to the session.
Check:
~/.cache/lxsession/LXDE/run.log
Yes, but they are heavy and may perform poorly on older devices. LXDE is recommended.
No, they require kernel features unavailable in proot.
Yes. proot-distro supports ARM, ARM64, and x86_64 depending on Termux architecture.
Run:
rm -f /tmp/.X1-lock /tmp/.X11-unix/X1Then:
vncserver :1Check:
~/.cache/lxsession/LXDE/run.log
Try:
- Lower resolution:
vncserver -geometry 1280x720 :1 - Disable compositing in LXDE
- Use a lighter distro (Alpine, Debian minimal)
Install it:
apt install proot-distro -yContributions, ideas, and improvements are welcome!
Feel free to:
- Open an issue
- Submit a pull request
- Suggest features
- Share creative use‑cases
This project is built for people who love repurposing old hardware, reducing e‑waste, and exploring what’s possible with minimal resources.
If you have ideas, improvements, or want to contribute, feel free to reach out or open an issue.
