Chroot Distro

chroot-distro: Installs GNU/Linux distributions in a chroot environment on Android.

The idea is inspired by proot-distro.

/data/local/chroot-distro/
├── .backup/           # Backup folder for distributions
├── .rootfs/           # Minimal root filesystem used for bootstrapping distributions
├── <distro>/          # Folder for each installed distribution (e.g., ubuntu, debian)
├── <distro>/          # Another folder for a different installed distribution
├── .config/           # Configuration folder for chroot-distro
│   ├── <distro>       # Empty file representing a custom distribution
│   ├── fix_suid       # File for handling SUID permission fixes
│   ├── ram_bind       # Configuration for RAM disk binding to improve performance
│   ├── android_bind   # Configuration for binding the Android environment with chroot

Note: If the system is not Android, the main path is /opt/chroot-distro

Requirements

Rooted Android Device

All root implementations are compatible.

You can use chroot-distro on any terminal, for example: MiXplorer, MT Manager, Termux, TWRP and Android Terminal Emulator (ADB Shell).

BusyBox for Android NDK

Install the latest BusyBox for Android NDK by osm0sis Magisk/KSU/APATCH module.

Alternative BusyBox

Distro Paths

System Points

<distro>/
├── /dev
├── /sys
├── /proc
└── /dev/pts

Optional Mounts

chroot-distro android-bind <enable|disable>:

Binding all Android root directories not mounted by default for full environment access.

Supported Distributions

Notes:

Usage Warning

Notice

chroot-distro requires root access to function. While running as root:

Careful

Before running chroot-distro:

Remember

This warning applies to all root-level operations, not just chroot-distro.

As they say: With great power comes great responsibility.

Commands

Basic Commands

chroot-distro help                        # Display this help message
chroot-distro env                         # Display environment information
chroot-distro list                        # List available distributions
chroot-distro list -i|--installed         # List installed distributions 
chroot-distro download <distro> [link]    # Download a distribution
chroot-distro redownload <distro> [link]  # Redownload a distribution
chroot-distro add <distro>                # Add a custom distribution
chroot-distro rename <old> <new>          # Rename a distribution
chroot-distro delete <distro>             # Delete a distribution (rootfs file only)
chroot-distro remove <distro>             # Remove all files related to a distribution

Note:

Installation Commands

chroot-distro install <distro>              # Install a distribution
chroot-distro reinstall <distro>            # Reinstall a distribution
chroot-distro reinstall --force <distro>    # Force reinstall
chroot-distro uninstall <distro>            # Uninstall a distribution
chroot-distro uninstall --force <distro>    # Force uninstall

Backup and Restore

chroot-distro backup <distro> [path]           # Create a backup
chroot-distro unbackup <distro>                # Remove a backup
chroot-distro restore <distro> [path]          # Restore from a backup
chroot-distro restore --default <distro>       # Restore to default settings

Notes:

Mount

chroot-distro mount <distro> # command to mount rootfs without entering

Unmount Commands

chroot-distro unmount <distro|all>                 # Unmount system points
chroot-distro unmount --force --all <distro|all>   # Force unmount all mounts

Notes:

Execute Commands

chroot-distro command <distro> "command"       # Run a command in the distribution
chroot-distro login <distro>                   # Log in to the distribution

Notes:

Example Usage

chroot-distro download ubuntu
chroot-distro install ubuntu
chroot-distro login ubuntu
chroot-distro command debian "sudo -i -u root"
chroot-distro backup ubuntu /sdcard/backup

Replace <distro> with the desired distribution identifier.

Settings Commands

chroot-distro android-bind <enable|disable>

chroot-distro fix-suid <enable|disable>

chroot-distro ram-bind <enable|disable>

Installation

  1. Download the latest release from the table below.
  2. Install via a module manager (e.g., Magisk) or flash through a custom recovery.

Screenshot Examples

Debian console

Desktop Environment with VNC

Debian GUI over VNC Ubuntu GUI over VNC

Desktop Environment with Termux-X11

Gui over Termux-X11 For a complete setup guide of VNC and Termux-X11, see android_gui.md.

chroot-distro on Gnu/Linux

Gnu_Linux chroot-distro was originally designed for Android, but it has also been made compatible with GNU/Linux systems. Installation instructions for GNU/Linux can be found here: how-to.md.

How-to Instructions

For detailed instructions on:

See how-to.md.

Development Guide

For full development instructions, see development_guide.md.

Environment Variables for chroot-distro Configuration

Semantic Versioning

chroot-distro uses semantic versioning for version numbers. Versioning uses three levels: major, minor and patch. Major version changes when there are breaking changes in API. Minor version changes for new features (or significant changes that don’t break compatibility). Patch version is only for bug fixes or very small changes (no breaking changes).

Software License

This software is licensed under the GNU General Public License v3.0 (GPL-3.0). You are free to:

Full license text: GNU GPL v3

Special Thanks

Special thanks to everyone who contributed to and tested chroot-distro.

Faced an Issue?

If you encounter any problems while using chroot-distro, please open an issue here.

If you found this project helpful and would like to support the developer, you can donate via Bitcoin:

Bitcoin Address: 1LksFFCP2HPdpVsUxfFmZShJFnLLrkZTro

Install chroot-distro

Download Module

warning : required busybox for android ndk module

Module Info

Search on : Google Bing Yandex