https://github.com/Magisk-Modules-Alt-Repo/chroot-distro
Install Gnu/Linux distributions on Android
https://github.com/Magisk-Modules-Alt-Repo/chroot-distro
Last synced: 4 months ago
JSON representation
Install Gnu/Linux distributions on Android
- Host: GitHub
- URL: https://github.com/Magisk-Modules-Alt-Repo/chroot-distro
- Owner: Magisk-Modules-Alt-Repo
- License: gpl-3.0
- Created: 2024-03-11T13:25:37.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-08-20T11:49:22.000Z (5 months ago)
- Last Synced: 2025-08-20T13:12:51.397Z (5 months ago)
- Language: Shell
- Homepage:
- Size: 4.49 MB
- Stars: 327
- Watchers: 8
- Forks: 19
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-android-root - Chroot Distro - Install Gnu/Linux distributions on Android. `FOSS` `[M]` (🔧 Development and Debugging / Themes and Visual Mods)
README
# chroot-distro
***chroot-distro***: Installs GNU/Linux distributions in a chroot environment on Android.
> The idea is inspired by [proot-distro](https://github.com/termux/proot-distro).
+ Directory Structure
```
/data/local/chroot-distro/
├── .backup/ # Backup folder for distributions
├── .rootfs/ # Minimal root filesystem used for bootstrapping distributions
├── / # Folder for each installed distribution (e.g., ubuntu, debian)
├── / # Another folder for a different installed distribution
├── .config/ # Configuration folder for chroot-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](https://github.com/osm0sis/android-busybox-ndk) by [osm0sis](https://github.com/osm0sis) Magisk module.
- **Recommended:** v1.36.1 (stable)
- **Avoid:** v1.32.1 (known bugs)
- **Note:** Outdated versions may cause issues with rootfs downloads.
### Alternative BusyBox
- BusyBox from Magisk, KernelSU, or APatch (without the NDK module) is community-supported but may lead to bugs.
- Additionally, BusyBox that is automatically detected is also supported, such as the one provided by **Termux** or the user's environment.
## Distro Paths
### System Points
```
/
├── /dev
├── /sys
├── /proc
└── /dev/pts
```
### Optional Mounts
`chroot-distro android-bind `:
Binding all Android root directories not mounted by default for full environment access.
## Supported Distributions
*Notes*:
- Use lowercase identifiers for it to be properly identified.
- Some distributions may not support your device architecture. The main supported architectures are:
`armv7 arm64 i686 amd64`
| 
 Ubuntu | 
    Arch    | 
  Fedora   | 
  Debian  | 
  Rocky | 
 CentOS Stream  | 
  Manjaro   | 
   Kali    | 
  Parrot  | 
  Alpine  | 
 OpenSUSE  | 
  Deepin  | 
 BackBox | 
 Chimera  | 
 OpenKylin | 
  Gentoo  | 
  Artix  | 
  Adélie  | 
   Void  |
|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|
| `ubuntu`| `arch` | `fedora`| `debian`| `rocky` | `centos_stream` | `manjaro`| `kali` | `parrot`| `alpine`| `opensuse` | `deepin`| `backbox` | `chimera` | `openkylin`| `gentoo`| `artix` | `adelie`| `void` |
## Usage Warning
### Notice
chroot-distro requires root access to function. While running as root:
* There's a small possibility of unintended file deletion
* System files could be accidentally modified
* Corner cases might exist despite thorough testing
### Careful
Before running chroot-distro:
* Always backup your important files
* Always backup your system partitions
### 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
```bash
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 [link] # Download a distribution
chroot-distro redownload [link] # Redownload a distribution
chroot-distro add # Add a custom distribution
chroot-distro rename # Rename a distribution
chroot-distro delete # Delete a distribution (rootfs file only)
chroot-distro remove # Remove all files related to a distribution
```
**Note:**
- `[link]` is an optional parameter for downloading a custom distribution.
### Installation Commands
```bash
chroot-distro install # Install a distribution
chroot-distro reinstall # Reinstall a distribution
chroot-distro reinstall --force # Force reinstall
chroot-distro uninstall # Uninstall a distribution
chroot-distro uninstall --force # Force uninstall
```
### Backup and Restore
```bash
chroot-distro backup [path] # Create a backup
chroot-distro unbackup # Remove a backup
chroot-distro restore [path] # Restore from a backup
chroot-distro restore --default # Restore to default settings
```
**Notes:**
- Use `--default` or `-d` to restore the original installation settings.
- Specify a custom `[path]` for backup/restore operations.
- For older backups, use `--force` cautiously to avoid issues like system mount conflicts or storage limitations.
### Mount
```bash
chroot-distro mount # command to mount rootfs without entering
```
### Unmount Commands
```bash
chroot-distro unmount # Unmount system points
chroot-distro unmount --force --all # Force unmount all mounts
```
**Notes:**
- You can unmount all distros with `unmount all`
- Use `--force` to close processes accessing system points.
- Use `--all` to unmount system, normal, and loopback mounts.
### Execute Commands
```bash
chroot-distro command "command" # Run a command in the distribution
chroot-distro login # Log in to the distribution
```
**Notes:**
- Enclose commands in quotes for the `command` operation.
- The `command` operation executes and returns to the host system.
### Example Usage
```bash
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 `` with the desired distribution identifier.*
### Settings Commands
```bash
chroot-distro android-bind
```
- Default set to enable.
- Binds all Android root directories.
```bash
chroot-distro fix-suid
```
- Default set to enable.
- Auto-fixes the setuid issue.
```bash
chroot-distro ram-bind
```
- Default set to enable.
- Binds some paths in the distro to RAM for performance improvement.
## Installation
1. Download the [latest release](https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/releases/latest) from the table below.
2. Install via a module manager (e.g., Magisk) or flash through a custom recovery.
## Screenshot Examples
### Desktop Environment with VNC
### Desktop Environment with Termux-X11
For a complete setup guide of VNC and Termux-X11, see [android_gui.md](docs/android_gui.md).
### chroot-distro on 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](docs/how-to.md).
## How-to Instructions
For detailed instructions on:
- Fixing `sudo`
- Adding a custom distribution
- Running `chroot-distro` on GNU/Linux
- Deleting a `chroot-distro`
See [how-to.md](docs/how-to.md).
## Development Guide
For full development instructions, see [development_guide.md](docs/development_guide.md).
## Environment Variables for chroot-distro Configuration
- **Change default `chroot-distro` path**:
```bash
export CHROOT_DISTRO_PATH=
```
- **Manual specification for `busybox`**:
```bash
export CHROOT_DISTRO_BUSYBOX=
```
Used to manually specify the path to the busybox command.
- **Skip tmpfs mount for `/tmp`**:
```bash
export CHROOT_DISTRO_TMP=false
```
Useful in some cases.
- **Skip exit on errors (unsafe)**:
```bash
export CHROOT_DISTRO_EXIT=false
```
Allows bypassing automatic exit on errors.
- **Disable mounting**:
```bash
export CHROOT_DISTRO_MOUNT=false
```
Prevents mounting of file systems during execution.
- **Developer-specific setting**:
```bash
export CHROOT_DISTRO_LOG=
```
Reserved for developers, explained in [development_guide.md](docs/development_guide.md).
## 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).
- **Major (X)**: Changes when API breaks compatibility
- **Minor (Y)**: Changes for new features (no compatibility breaks)
- **Patch (Z)**: Bug fixes and small updates (no breaking changes)
## Software License
This software is licensed under the GNU General Public License v3.0 (GPL-3.0). You are free to:
- Use, modify, and distribute this software
- Access and modify the source code
- Use for commercial purposes
Full license text: [GNU GPL v3](LICENSE)
## 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](https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/issues/).
## Donate
If you found this project helpful and would like to support the developer, you can donate via Bitcoin:
**Bitcoin Address:** `1LksFFCP2HPdpVsUxfFmZShJFnLLrkZTro`