Complete Linux Installer is an open-source Android application designed to download, provision, and run full-featured Linux distributions (including Ubuntu 26.04 LTS, Debian 12, Fedora 44, Alpine Linux, Arch Linux ARM, Kali Linux, and Void Linux) natively on Android devices without requiring root permissions.
Tip
📲 Now Live on the Google Play Store!
Download on Google Play | Join Beta Testing Track
Powered by a native PRoot user-space engine, a multi-session POSIX PTY terminal bridge, and a modern Jetpack Compose Material 3 interface, Complete Linux Installer transforms your Android phone or tablet into a portable Linux workstation, server host, desktop environment, and development platform.
Note
Active Development & Community Support: Complete Linux Installer is actively developed and maintained. Join our Discord Community for announcements and discussion, or submit an issue on GitHub if you discover any bugs!
 Containers Dashboard |
 Multi-Tab Terminal & Hotkeys |
 Container Overview & Service Controls |
 1-Click Software Hub |
 Distro Setup Wizard |
 Architecture & Onboarding |
- 🔒 100% Rootless & Completely Isolated: Runs entirely in Android user-space using PRoot ptrace system call interception. Zero root access, unlocked bootloaders, or Android system partition modifications required. Safe and sandboxed without touching your personal files or host OS.
- 🐧 Multi-Distribution Linux Catalog: Install and switch between 7 distinct Linux distributions tailored for different performance profiles and use cases:
- Ubuntu 26.04 LTS: Official base LTS environment with APT package management.
- Debian 12: Ultra-stable lightweight alternative with vast software repositories.
- Fedora 44: Modern Red Hat-family distribution powered by the
dnfpackage manager. - Alpine Linux 3.21: Minimalist musl/busybox environment (~10MB rootfs) with instant boot times and tiny memory footprint.
- Arch Linux ARM: Bleeding-edge rolling release environment powered by the
pacmanpackage manager. - Kali Linux CLI Tools: Specialized security auditing and penetration testing tools environment.
- Void Linux: Independent general-purpose distribution with the blazing-fast
xbpspackage manager.
- 📑 Concurrent Multi-Tab Terminal: Run, switch, and manage multiple independent interactive terminal sessions simultaneously with isolated PTY subprocesses, custom tab titles, session indicators, and container-specific terminal sessions.
- ⌨️ Termux-Style Grid Hotkeys & Session Safety: Aligned equal-width 7-column extra keys grid modeled after Termux for consistent muscle memory, custom hotkey editor, and a safety confirmation prompt before stopping active terminal sessions.
- 🎛️ Installed Containers Dashboard: Manage multiple Linux distributions installed side-by-side on disk. Includes per-container storage tracking, live RAM and storage gauge dials, isolated process monitoring (
ps aux), open TCP port listeners with 1-tap browser launcher, and 1-touch service quick-launchers (VNC, Web Terminal, NGINX, SSH). - 🖥️ Full Graphical Desktop Access (GUI): One-click installation of a complete XFCE4 Desktop Environment with TigerVNC support for full windowed desktop access directly on your phone, tablet, or external display.
- 🌐 Web Terminal & Remote VS Code:
- Browser Web Terminal (ttyd): Access full interactive shells from any local browser over Wi-Fi without SSH clients.
- VS Code Server (code-server): Run full Visual Studio Code in your browser with extensions and syntax highlighting.
- 🐳 1-Click Docker & Container Tools: Pull and run containers from Docker Hub in user space without root or cgroup requirements via
udocker, with official Docker CLI and Docker Compose wrappers. - 🛠️ 1-Click Software Hub & Multi-Package Managers: Tailored software presets and native package manager integration (
apt,dnf,apk,pacman,xbps):- Desktop Environments: XFCE4 Desktop, XFCE Terminal, TigerVNC Server.
- Containers & Tools: Docker CLI, Docker Compose, and udocker engine.
- Web & Database: NGINX HTTP web server + SQLite3.
- Remote & Cloud IDE: OpenSSH Server daemon, Web Terminal (
ttyd), and Visual Studio Code Server (code-server). - Development Stacks: Python 3 (pip, venv, GCC), Node.js (npm, Yarn, Neovim), and Android Developer Tools (OpenJDK 17, ADB, Gradle).
- 👋 First-Launch Onboarding & Welcome Guide: Integrated introduction screen detailing container architecture, sandboxing safety, and multi-container capabilities before entering the setup wizard.
- 🗑️ Safe Container Deletion Feedback: Dedicated full-screen deletion view with animated feedback, real-time step progress, and back-gesture protection during storage purging.
- 🛡️ Background Execution & WakeLock: Android Foreground Service with CPU WakeLock keeping long compilation tasks, downloads, SSH sessions, and background web servers alive when the app is minimized.
- 💾 RootFS Backup, Restore & Incremental Upgrades: 1-tap
.tar.gzcontainer backup export/import and schema upgrades without wiping user files. - 🌐 Multi-Architecture Support: Native architecture detection and rootfs support for ARM64 (aarch64), x86_64 (amd64), and ARMv7 (armhf).
- 📁 Storage & Device Binding: Automatic mounting of Android storage (
/sdcard) and key system file descriptors (/proc,/sys,/dev).
+-------------------------------------------------------------------------------+
| Android UI Layer (Jetpack Compose Material 3) |
| WelcomeScreen | DashboardScreen | ContainerDetail (3 Tabs) | TerminalScreen |
| (Onboarding) | (Multi-Distro) | Overview / Software / Set| Multi-Tab Strip |
+-------------------------------------------------------------------------------+
|
v
+-------------------------------------------------------------------------------+
| Kotlin Engine Core |
| ContainerManager | PRootEngine | TerminalManager & Session | SoftwareInstaller|
+-------------------------------------------------------------------------------+
| |
v v
+-----------------------------+ +-------------------------------------+
| Native JNI Layer | | PRoot Subsystem |
| pty.cpp (POSIX PTY) | | libproot.so |
| - Concurrent PTYs | | - ptrace syscall intercept|
| - posix_openpt() | | - Rootfs isolation (-r) |
| - TIOCSWINSZ resize | | - Fake root mapping (-0) |
| - fork() & execve() | | - Bind mounts (/sdcard) |
+-----------------------------+ +-------------------------------------+
| |
+----------------------+----------------------+
|
v
+-------------------------------------------------------------------------------+
| Guest Linux Rootfs (Ubuntu / Debian / Fedora / Alpine / etc) |
| apt / dnf / apk / pacman / xbps, shells (/bin/bash, /bin/sh), XFCE, VNC |
| Isolated per-container rootfs folders, process trees, and ports |
+-------------------------------------------------------------------------------+
PRoot uses the ptrace system call mechanism to bind system calls made by guest Linux binaries. It translates paths and file operations on-the-fly, creating the illusion that guest binaries are running with root privileges (-0) inside a standard Linux filesystem layout (/), even though everything resides inside the app's internal private storage directory (context.filesDir).
- Link2Symlink (
PROOT_LINK2SYMLINK) Support: Android SELinux policies restrict native hard-link creation on internal storage for untrusted app UIDs. The app manages a dedicatedl2sstore bound into PRoot via-b, translating hard-link requests (link/linkat) into transparent relative symlinks for package managers likedpkg,apt,dnf,pacman, andxbps.
Interactive terminal applications (like vim, htop, tmux, bash) require a Unix pseudo-terminal (PTY) to handle window dimensions, signals (SIGINT, SIGTSTP), and line buffering. The native C++ layer (pty.cpp) allocates a POSIX PTY per tab via posix_openpt(), configures window size (TIOCSWINSZ), and spawns PRoot child processes via fork() and execve(). Each tab runs an independent, isolated session that buffers output in the background.
- Provisions and manages multiple independent container directories side-by-side.
- Extracts minimal distribution archives (Ubuntu, Debian, Fedora, Alpine, Arch, Kali, Void) using native streaming extractors with hard-link translation.
- Automatically configures guest networking, public DNS resolvers (
/etc/resolv.conf), hostname binding (user@ContainerName), and cross-distribution user provisioning (/etc/passwd,/etc/group,/etc/shadow). - Accurately tracks per-container disk consumption across hard links (
du -sk) and scopes process monitoring and active port detection strictly to each container.
Complete Linux Installer provisions environments using official root filesystem images directly from upstream Linux distribution project maintainers. We gratefully acknowledge the developers and maintainers of these projects:
| Linux Distribution | Maintainer / Project | Description | Source / Reference |
|---|---|---|---|
| Ubuntu Base | Canonical Ltd. | Official minimal base rootfs tarballs for Ubuntu Linux. | Ubuntu Base Releases |
| Debian | Debian Project / debuerreotype | Reproducible, official Debian container rootfs pipeline maintained by the Debian cloud team. | debuerreotype Releases / Debian |
| Fedora Linux | Fedora Project | Official minimal container base rootfs images powered by the DNF package manager. | Fedora Container Base |
| Alpine Linux | Alpine Linux Development Team | Official ultra-lightweight Alpine Linux minirootfs tarballs. | Alpine Linux Releases |
| Arch Linux ARM | Arch Linux ARM Project | Official rolling base rootfs images for ARM architectures. | Arch Linux ARM |
| Kali Linux | Offensive Security / Kali Linux Team | Official NetHunter minimal rootfs images with Kali Linux repositories. | Kali Linux / Kali NetHunter Images |
| Void Linux | Void Linux Project | Official independent rootfs tarballs featuring the XBPS package system. | Void Linux Downloads |
| Component | Description & Purpose | License / Upstream |
|---|---|---|
PRoot (libproot.so) |
User-space implementation of chroot, mount --bind, and root emulation using ptrace. |
PRoot Project / GPL-2.0 |
libandroid-shmem (libandroid-shmem.so) |
System V shared memory emulation wrapper for Android ashmem/memfd kernel interfaces. | libandroid-shmem |
talloc (libtalloc.so) |
Hierarchical pool-based memory allocator developed by the Samba project, required by PRoot. | Samba talloc / LGPL-3.0 |
| Termux Project | Architectural references for PRoot execution and PTY subprocess management on Android. | Termux / GPL-3.0 |
| JetBrains Mono | Bundled monospace font used in the terminal renderer. | JetBrains/JetBrainsMono / SIL OFL 1.1 |
| Ubuntu Mono | Bundled monospace font option for the terminal. | Ubuntu Font Family / Ubuntu Font Licence |
- Android Studio: Ladybug (2024.2.1) or newer recommended.
- JDK: Java 21 (matching the Gradle JVM toolchain).
- Android NDK: Version 28.2.13676358 (configured for C++ CMake compilation of
pty.cpp).
-
Clone the repository:
git clone https://github.com/devwithzachary/LinuxOnAndroid.git cd LinuxOnAndroid -
(Optional) Rebuild Native Libraries: Pre-compiled binaries are maintained under
app/src/main/jniLibs/for rapid daily builds. To recompilelibproot.so,libproot_loader.so,libproot_loader32.so,libtalloc.so, andlibandroid-shmem.sofrom source across all target architectures (arm64-v8a,armeabi-v7a,x86_64):./scripts/build_native_libs.sh
Note: This script compiles all native components strictly from source across all supported architectures.
-
Run Unit Tests:
./gradlew testDebugUnitTest
-
Build Debug APK:
./gradlew assembleDebug
-
Install on connected device via ADB:
adb install app/build/outputs/apk/debug/app-debug.apk
To verify that download mirrors, archive hashes, and PRoot runtime execution remain fully functional across all 7 supported distributions, run the automated installation test script:
./scripts/test_distro_installations.sh- On first launch, the Welcome Screen introduces the container architecture, rootless virtualization, and multi-container capabilities.
- Tap Get Started to enter the Setup Wizard.
- Choose your distribution from the catalog (Ubuntu 26.04 LTS, Debian 12, Fedora 44, Alpine Linux 3.21, Arch Linux ARM, Kali Linux CLI, or Void Linux) and select your target architecture.
- Tap Download & Install RootFS to automatically stream, verify, unpack, and provision your initial container.
- Navigate to the Terminal tab to interact with your environment.
- Tap the
+button in the top tab strip to launch additional concurrent terminal sessions. - Long-press any tab chip to give it a custom name (e.g. "Server", "Python", "Compiler").
- Use the pinned extra-keys toolbar for fast access to
Ctrl,Alt,Esc,Tab,Paste, and directional navigation arrows. - Tap the sliders icon to customize your hotkey layout or add custom key shortcuts.
- Tap into any container from the Dashboard and navigate to the Software tab.
- Select any desired service and tap Install:
- XFCE4 Desktop + VNC Server: Connect using any Android VNC viewer at
127.0.0.1:5901. - Web Terminal (ttyd): Open in any local browser at
http://<device_ip>:8080(or7681). - VS Code Server (code-server): Access full VS Code in your browser at
http://<device_ip>:8443. - Docker Tools (udocker): Run containers with standard
dockeranddocker-composecommands. - NGINX Web Server / OpenSSH Server: Host local websites and connect securely over LAN.
- XFCE4 Desktop + VNC Server: Connect using any Android VNC viewer at
- Once installed, launch the service with a single tap directly from the Overview tab service card.
- Install More Containers: Add additional distinct Linux distributions anytime from the Dashboard.
- Per-Container Isolation: Each container runs isolated filesystem mounts, independent process trees (
ps aux), and separate TCP port listeners. - Backup & Restore: Export and import full
.tar.gzcontainer snapshots under Settings > Backup & Restore. - Safe Container Deletion: Remove unwanted containers safely with real-time progress feedback and storage purging.
Contributions, bug reports, and feature requests are welcome! Feel free to check out the issues page or submit a pull request.
Please review our AI Usage Policy for guidelines on using AI coding assistants when contributing to this project. All code submitted must be thoroughly reviewed and personally owned by the human author; automated bot PRs are not accepted.
This project is licensed under the GNU General Public License v2.0 (GPL-2.0-or-later) - see the LICENSE file for details. Included binaries (PRoot, talloc, libandroid-shmem) remain under their respective open-source licenses.