Magisk-Modules-Alt-Repo

chroot-distro

v2.1.0guide

Install Gnu/Linux distributions on Android

★500 stars
•Development & Instrumentation•by Magisk-Modules-Alt-Repo•GPL-3.0•Updated Jun 11, 2025
Platforms:
✓ Magisk
Download v2.1.0Starting download...GitHub Source
chroot-distro.zip

Overview

Maintained by Magisk-Modules-Alt-Repo, chroot-distro is an advanced distribution deployment utility that brings native GNU/Linux operating systems to rooted Android devices.

Inspired by the workflow of PRoot Distro but designed for root users, chroot-distro leverages Linux’s native chroot system call. This allows developers to run complete Linux server stacks, compilers, network analysis tools, and desktop environments at bare-metal speeds directly alongside Android.

Technical Architecture & How It Works

Native Containerization & Mount Namespaces

chroot-distro manages containerized environments under /data/local/chroot-distro/:

  1. Rootfs Bootstrapping: Downloads minimal official rootfs tarballs for selected Linux distributions directly from upstream mirrors.
  2. System Node Binding: Mounts virtual filesystems into the distribution root:
    • /proc and /sys for kernel state inspection.
    • /dev and /dev/pts for pseudoterminal handling and hardware access.
    • /sdcard or /data/media/0 for shared storage access.
  3. Android Environment Bridges: Bridges DNS configuration (/etc/resolv.conf) and user permissions between Android and the Linux container.

Installation & Setup

  1. Flash the BusyBox for Android NDK module (version 1.36.1 recommended).
  2. Download and flash the chroot-distro-*.zip module in your root manager.
  3. Open Termux or any root terminal app and run: 
    su
chroot-distro help

Configuration & Usage

Installing a Distribution

# List available distributions
chroot-distro list

# Install Debian or Ubuntu
chroot-distro install debian

Entering the Linux Environment

chroot-distro login debian

Inside the container, you have a full standard APT package manager:

apt update && apt install python3 git build-essential htop

Troubleshooting & Common Issues

  • Download or Extraction Fails: Ensure you have installed BusyBox NDK. Using Android’s stock Toybox tar command will fail on distribution symlinks and hardlinks.
  • Permission Denied on Android Storage: To enable access to your phone’s internal storage inside the chroot, configure android_bind in /data/local/chroot-distro/.config/.

Frequently Asked Questions

How does chroot-distro differ from Termux's proot-distro?

PRoot works without root by intercepting system calls with ptrace, which adds significant CPU overhead. chroot-distro uses Linux's native chroot system call, running Linux processes directly on the kernel with zero translation overhead and full root capabilities.

Why is BusyBox for Android NDK required?

chroot-distro scripts rely on standard GNU/Linux command flags (in tar, wget, grep, and mount) that Android's default toybox/toolbox implementation does not support. Osm0sis's BusyBox NDK provides full POSIX command parity.