Chroot Distro

Install Linux distributions on Android devices using chroot

Prerequisites

• Back up important files before use
• Rooted Android Device
• BusyBox: osm0sis/android-busybox-ndk (Recommended: v1.36.1)

Tip

KernelSU users do not need to flash busybox as it has built-in busybox support.

---

Supported Distributions

---

Quick Start

# List available distributions
chroot-distro list

# Install a distribution
chroot-distro install debian

# Login to the distribution
chroot-distro login debian

---

Command Reference

Command	Aliases	Description
help	--help, -h, he, hel	Display help information
version	--version, -v	Show version information
list	li, ls	List available distributions
list-running		List currently running distros
install	i, in, ins, add	Install a distribution
login	sh	Enter distribution shell
remove	rm	Remove a distribution
unmount	umount, um	Unmount distribution
clear-cache	clear, cl	Clear downloaded files

---

Commands

help

Display general help or command-specific help information:

chroot-distro help
chroot-distro <command> --help

list

List all available distributions with their aliases, installation status, and additional information:

chroot-distro list

list-running

List currently mounted checking for active mount points:

chroot-distro list-running

install <distro>

Install a supported distribution:

chroot-distro install debian

Available Options

• --skip-useradd – Skip the user creation prompt during installation

Environment Variables

• SKIP_USERADD=1 – Same as --skip-useradd flag

User Creation

During installation, you will be prompted to create a normal user account. The created user:

• Gets the same UID as Termux, to enabling access to Termux files (e.g., with --termux-home)

To skip this prompt entirely:

chroot-distro install debian --skip-useradd

or

SKIP_USERADD=1 chroot-distro install debian

To automate user creation without interactive prompts:

chroot-distro install debian --adduser username password

login <distro>

Enter a shell session inside the installed distribution:

chroot-distro login debian

Available Options

• --user <username> – Login as a specified user (user must exist in chroot environment)
• --isolated - Run the specified distro in an isolated chroot environment
• --shared-tmp - Share Termux tmp directory (no compatible with --isolated)
• --termux-home – Mount Termux home directory inside chroot (no compatible with --isolated)
• --bind <host_path>:<chroot_path> – Bind mount a path from host to chroot (no compatible with --isolated)
• --work-dir <path> – Set custom working directory (default: user's home directory)

Execute Commands

Run commands directly inside the chroot environment:

chroot-distro login debian -- /bin/sh -c 'apt update'

Use -- to separate chroot-distro options from the target command.

unmount <distro>

Unmount all mount points associated with a distribution:

chroot-distro unmount debian

Options

• --help – Display help for this command

Examples

chroot-distro unmount debian

remove <distro>

Permanently remove an installed distribution.

Warning

This operation is irreversible and does not prompt for confirmation.

chroot-distro remove fedora

clear-cache

Remove all downloaded rootfs archives to free up storage space:

chroot-distro clear-cache

---

Service Management

Chroot Distro includes a lightweight service manager called serviced it can start a systemd process without systemd

Configuration

The service manager behavior can be configured via the settings.conf file located at:

/data/local/chroot-distro/data/settings.conf

Tip

This file can be easily configured using the WebUI.

Options

Option	Description
SERVICED	Set to true to enable the service manager.
SERVICED_VERBOSE_MODE	Set to true to enable verbose logging for debugging service start issues.

Usage

When SERVICED is enabled, chroot-distro will automatically start the built-in serviced manager when you login. You can then use it to manage services:

# Start a service
serviced start docker

# Start all enabled services
serviced start

# Enable a service to start on boot
serviced enable docker

# Disable a service
serviced disable docker

# Check status
serviced status docker

# List all services
serviced list

---

Termux Integration

To simplify usage from Termux, create a wrapper script:

1. Open Termux and run:

nano $PREFIX/bin/chroot-distro

2. Paste the following content:

#!/data/data/com.termux/files/usr/bin/bash

args=""
for arg in "$@"; do
    escaped_arg=$(printf '%s' "$arg" | sed "s/'/'\\\\''/g")
    args="$args '$escaped_arg'"
done

su -c "/system/bin/chroot-distro $args"

3. Make the script executable:

chmod +x $PREFIX/bin/chroot-distro

• You can now use chroot-distro directly from Termux without switching to root user manually.

---

Screenshots

Docker Support	Flatpak Support

To know more check our wiki

---

Support the Project

If you find this project helpful and would like to support its development, consider buying me a coffee! Your support helps maintain and improve this project.

Cryptocurrency Donations:

• USDT (BEP20,ERC20): 0x1d216cf986d95491a479ffe5415dff18dded7e71
• USDT (TRC20): TCjRKPLG4BgNdHibt2yeAwgaBZVB4JoPaD
• BTC: 13Q7xf3qZ9xH81rS2gev8N4vD92L9wYiKH
• DOGE: DJkMCnBAFG14TV3BqZKmbbjD8Pi1zKLLG6
• ETH: 0x1d216cf986d95491a479ffe5415dff18dded7e71

Every contribution, no matter how small, helps keep this project alive and growing! ❤️

---

License

This project is licensed under the GNU General Public License v3.0

Copyright (C) 2025 sabamdarif

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

---

Acknowledgments:

Special thanks to:

• proot-distro
• Magisk-Modules-Alt-Repo/chroot-distro
• ravindu644/Ubuntu-Chroot
• gdraheim/docker-systemctl-replacement

---

⭐ If you enjoy this project, consider giving it a star!