{"id":31194813,"url":"https://github.com/Magisk-Modules-Alt-Repo/chroot-distro","last_synced_at":"2025-09-20T02:05:00.412Z","repository":{"id":227998333,"uuid":"770391171","full_name":"Magisk-Modules-Alt-Repo/chroot-distro","owner":"Magisk-Modules-Alt-Repo","description":"Install Gnu/Linux distributions on Android ","archived":false,"fork":false,"pushed_at":"2025-08-20T11:49:22.000Z","size":4705,"stargazers_count":327,"open_issues_count":14,"forks_count":19,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-08-20T13:12:51.397Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Magisk-Modules-Alt-Repo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-03-11T13:25:37.000Z","updated_at":"2025-08-20T11:49:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"ce14212b-a189-4713-819a-3f76794c0ac5","html_url":"https://github.com/Magisk-Modules-Alt-Repo/chroot-distro","commit_stats":null,"previous_names":["magisk-modules-alt-repo/chroot-distro"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/Magisk-Modules-Alt-Repo/chroot-distro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Magisk-Modules-Alt-Repo%2Fchroot-distro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Magisk-Modules-Alt-Repo%2Fchroot-distro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Magisk-Modules-Alt-Repo%2Fchroot-distro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Magisk-Modules-Alt-Repo%2Fchroot-distro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Magisk-Modules-Alt-Repo","download_url":"https://codeload.github.com/Magisk-Modules-Alt-Repo/chroot-distro/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Magisk-Modules-Alt-Repo%2Fchroot-distro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276033070,"owners_count":25573474,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-20T02:00:10.207Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-20T02:02:24.519Z","updated_at":"2025-09-20T02:05:00.398Z","avatar_url":"https://github.com/Magisk-Modules-Alt-Repo.png","language":"Shell","readme":"# chroot-distro\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/downloads/Magisk-Modules-Alt-Repo/chroot-distro/total?label=Downloads\"/\u003e\n  \u003cimg src=\"https://img.shields.io/github/v/release/Magisk-Modules-Alt-Repo/chroot-distro?include_prereleases\u0026label=Release\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-GPLv3-blue.svg\"/\u003e\n\u003c/p\u003e\n\n![](https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/chroot-distro.jpg) \n\n***chroot-distro***: Installs GNU/Linux distributions in a chroot environment on Android.  \n\u003e The idea is inspired by [proot-distro](https://github.com/termux/proot-distro).\n\n+ Directory Structure\n```\n/data/local/chroot-distro/\n├── .backup/           # Backup folder for distributions\n├── .rootfs/           # Minimal root filesystem used for bootstrapping distributions\n├── \u003cdistro\u003e/          # Folder for each installed distribution (e.g., ubuntu, debian)\n├── \u003cdistro\u003e/          # Another folder for a different installed distribution\n├── .config/           # Configuration folder for chroot-distro\n│   ├── \u003cdistro\u003e       # Empty file representing a custom distribution\n│   ├── fix_suid       # File for handling SUID permission fixes\n│   ├── ram_bind       # Configuration for RAM disk binding to improve performance\n│   ├── android_bind   # Configuration for binding the Android environment with chroot\n```\n**Note:** If the system is not *Android*, the main path is `/opt/chroot-distro`\n\n## Requirements\n\n### Rooted Android Device\nAll root implementations are compatible.\n\nYou can use `chroot-distro` on any terminal, for example: MiXplorer, MT Manager, Termux, TWRP and Android Terminal Emulator (ADB Shell).\n\n### BusyBox for Android NDK\nInstall the [latest BusyBox for Android NDK](https://github.com/osm0sis/android-busybox-ndk) by [osm0sis](https://github.com/osm0sis) Magisk module.  \n- **Recommended:** v1.36.1 (stable)  \n- **Avoid:** v1.32.1 (known bugs)  \n- **Note:** Outdated versions may cause issues with rootfs downloads.\n\n### Alternative BusyBox\n- BusyBox from Magisk, KernelSU, or APatch (without the NDK module) is community-supported but may lead to bugs.\n- Additionally, BusyBox that is automatically detected is also supported, such as the one provided by **Termux** or the user's environment.\n\n## Distro Paths\n\n### System Points\n```\n\u003cdistro\u003e/\n├── /dev\n├── /sys\n├── /proc\n└── /dev/pts\n```\n\n### Optional Mounts\n\n`chroot-distro android-bind \u003cenable|disable\u003e`: \n\nBinding all Android root directories not mounted by default for full environment access. \n\n## Supported Distributions\n*Notes*: \n- Use lowercase identifiers for it to be properly identified.\n- Some distributions may not support your device architecture. The main supported architectures are:\n`armv7 arm64 i686 amd64`\n\n| \u003cimg src=\"https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/ubuntu.png\" width=\"50\"\u003e\u003cbr\u003e Ubuntu | \u003cimg src=\"https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/arch_linux.png\" width=\"50\"\u003e\u003cbr\u003e    Arch    | \u003cimg src=\"https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/fedora.png\" width=\"50\"\u003e\u003cbr\u003e  Fedora   | \u003cimg src=\"https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/debian.png\" width=\"50\"\u003e\u003cbr\u003e  Debian  | \u003cimg src=\"https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/rocky_linux.png\" width=\"50\"\u003e\u003cbr\u003e  Rocky | \u003cimg src=\"https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/centos.png\" width=\"50\"\u003e\u003cbr\u003e CentOS Stream  | \u003cimg src=\"https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/manjaro.png\" width=\"50\"\u003e\u003cbr\u003e  Manjaro   | \u003cimg src=\"https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/kali_linux.png\" width=\"50\"\u003e\u003cbr\u003e   Kali    | \u003cimg src=\"https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/parrot_security.png\" width=\"50\"\u003e\u003cbr\u003e  Parrot  | \u003cimg src=\"https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/alpine_linux.png\" width=\"50\"\u003e\u003cbr\u003e  Alpine  | \u003cimg src=\"https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/opensuse.png\" width=\"50\"\u003e\u003cbr\u003e OpenSUSE  | \u003cimg src=\"https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/deepin.png\" width=\"50\"\u003e\u003cbr\u003e  Deepin  | \u003cimg src=\"https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/backbox_linux.png\" width=\"50\"\u003e\u003cbr\u003e BackBox | \u003cimg src=\"https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/chimera_linux.png\" width=\"50\"\u003e\u003cbr\u003e Chimera  | \u003cimg src=\"https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/openkylin.png\" width=\"50\"\u003e\u003cbr\u003e OpenKylin | \u003cimg src=\"https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/gentoo.png\" width=\"50\"\u003e\u003cbr\u003e  Gentoo  | \u003cimg src=\"https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/artix_linux.png\" width=\"50\"\u003e\u003cbr\u003e  Artix  | \u003cimg src=\"https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/adelie_linux.png\" width=\"50\"\u003e\u003cbr\u003e  Adélie  | \u003cimg src=\"https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/void_linux.png\" width=\"50\"\u003e\u003cbr\u003e   Void  |\n|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|\n| `ubuntu`| `arch`  | `fedora`| `debian`| `rocky` | `centos_stream`  | `manjaro`| `kali`  | `parrot`| `alpine`| `opensuse` | `deepin`| `backbox`  | `chimera`  | `openkylin`| `gentoo`| `artix` | `adelie`| `void`  |\n\n## Usage Warning\n\n### Notice\nchroot-distro requires root access to function. While running as root:\n* There's a small possibility of unintended file deletion\n* System files could be accidentally modified\n* Corner cases might exist despite thorough testing\n\n### Careful\nBefore running chroot-distro:\n* Always backup your important files\n* Always backup your system partitions\n\n### Remember\nThis warning applies to all root-level operations, not just chroot-distro.\n\nAs they say: ***With great power comes great responsibility.***\n\n## Commands\n\n### Basic Commands\n```bash\nchroot-distro help                        # Display this help message\nchroot-distro env                         # Display environment information\nchroot-distro list                        # List available distributions\nchroot-distro list -i|--installed         # List installed distributions \nchroot-distro download \u003cdistro\u003e [link]    # Download a distribution\nchroot-distro redownload \u003cdistro\u003e [link]  # Redownload a distribution\nchroot-distro add \u003cdistro\u003e                # Add a custom distribution\nchroot-distro rename \u003cold\u003e \u003cnew\u003e          # Rename a distribution\nchroot-distro delete \u003cdistro\u003e             # Delete a distribution (rootfs file only)\nchroot-distro remove \u003cdistro\u003e             # Remove all files related to a distribution\n```\n**Note:**\n- `[link]` is an optional parameter for downloading a custom distribution.\n\n### Installation Commands\n```bash\nchroot-distro install \u003cdistro\u003e              # Install a distribution\nchroot-distro reinstall \u003cdistro\u003e            # Reinstall a distribution\nchroot-distro reinstall --force \u003cdistro\u003e    # Force reinstall\nchroot-distro uninstall \u003cdistro\u003e            # Uninstall a distribution\nchroot-distro uninstall --force \u003cdistro\u003e    # Force uninstall\n```\n\n### Backup and Restore\n```bash\nchroot-distro backup \u003cdistro\u003e [path]           # Create a backup\nchroot-distro unbackup \u003cdistro\u003e                # Remove a backup\nchroot-distro restore \u003cdistro\u003e [path]          # Restore from a backup\nchroot-distro restore --default \u003cdistro\u003e       # Restore to default settings\n```\n**Notes:**\n- Use `--default` or `-d` to restore the original installation settings.\n- Specify a custom `[path]` for backup/restore operations.\n- For older backups, use `--force` cautiously to avoid issues like system mount conflicts or storage limitations.\n\n### Mount \n```bash\nchroot-distro mount \u003cdistro\u003e # command to mount rootfs without entering\n```\n### Unmount Commands\n```bash\nchroot-distro unmount \u003cdistro|all\u003e                 # Unmount system points\nchroot-distro unmount --force --all \u003cdistro|all\u003e   # Force unmount all mounts\n```\n**Notes:**\n- You can unmount all distros with `unmount all`\n- Use `--force` to close processes accessing system points.\n- Use `--all` to unmount system, normal, and loopback mounts.\n\n### Execute Commands\n```bash\nchroot-distro command \u003cdistro\u003e \"command\"       # Run a command in the distribution\nchroot-distro login \u003cdistro\u003e                   # Log in to the distribution\n```\n**Notes:**\n- Enclose commands in quotes for the `command` operation.\n- The `command` operation executes and returns to the host system.\n\n### Example Usage\n```bash\nchroot-distro download ubuntu\nchroot-distro install ubuntu\nchroot-distro login ubuntu\nchroot-distro command debian \"sudo -i -u root\"\nchroot-distro backup ubuntu /sdcard/backup\n```\n*Replace `\u003cdistro\u003e` with the desired distribution identifier.*\n### Settings Commands\n\n```bash\nchroot-distro android-bind \u003cenable|disable\u003e\n```\n- Default set to enable.\n- Binds all Android root directories.\n```bash\nchroot-distro fix-suid \u003cenable|disable\u003e\n```\n- Default set to enable.\n- Auto-fixes the setuid issue.\n```bash\nchroot-distro ram-bind \u003cenable|disable\u003e\n```\n- Default set to enable.\n- Binds some paths in the distro to RAM for performance improvement.\n\n## Installation\n1. Download the [latest release](https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/releases/latest) from the table below.\n2. Install via a module manager (e.g., Magisk) or flash through a custom recovery.\n\n## Screenshot Examples \n![Debian  console](https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/screenshot/debian.png)\n### Desktop Environment with VNC\n![Debian GUI over VNC](https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/screenshot/debian_vnc.png)\n![Ubuntu GUI over VNC](https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/screenshot/ubuntu.png)\n### Desktop Environment with Termux-X11\n![Gui over Termux-X11](https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/parrot_termux_x11.jpg)\nFor a complete setup guide of VNC and Termux-X11, see [android_gui.md](docs/android_gui.md).\n### chroot-distro on Gnu/Linux \n![Gnu_Linux](https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/raw/main/images/gnu_linux.jpg) \n`chroot-distro` was originally designed for Android, but it has also been made compatible with GNU/Linux systems.\nInstallation instructions for GNU/Linux can be found here: [how-to.md](docs/how-to.md).\n## How-to Instructions  \nFor detailed instructions on:  \n- Fixing `sudo`  \n- Adding a custom distribution  \n- Running `chroot-distro` on GNU/Linux  \n- Deleting a `chroot-distro`  \n\nSee [how-to.md](docs/how-to.md).\n\n## Development Guide\nFor full development instructions, see [development_guide.md](docs/development_guide.md).\n\n## Environment Variables for chroot-distro Configuration\n- **Change default `chroot-distro` path**: \n  ```bash\n  export CHROOT_DISTRO_PATH=\u003cpath\u003e\n  ```\n- **Manual specification for `busybox`**:\n  ```bash\n  export CHROOT_DISTRO_BUSYBOX=\u003cpath\u003e \n  ```\n  Used to manually specify the path to the busybox command.\n- **Skip tmpfs mount for `/tmp`**: \n  ```bash\n  export CHROOT_DISTRO_TMP=false\n  ```\n  Useful in some cases.\n- **Skip exit on errors (unsafe)**:\n  ```bash\n  export CHROOT_DISTRO_EXIT=false\n  ```\n  Allows bypassing automatic exit on errors.\n- **Disable mounting**:\n  ```bash\n  export CHROOT_DISTRO_MOUNT=false\n  ```\n  Prevents mounting of file systems during execution.\n- **Developer-specific setting**:\n  ```bash\n  export CHROOT_DISTRO_LOG=\u003cvalue\u003e\n  ```\n  Reserved for developers, explained in [development_guide.md](docs/development_guide.md).\n\n## Semantic Versioning\n\n`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).\n\n- **Major (X)**: Changes when API breaks compatibility\n- **Minor (Y)**: Changes for new features (no compatibility breaks)\n- **Patch (Z)**: Bug fixes and small updates (no breaking changes)\n\n## Software License\n\nThis software is licensed under the GNU General Public License v3.0 (GPL-3.0). You are free to:\n- Use, modify, and distribute this software\n- Access and modify the source code\n- Use for commercial purposes\n\nFull license text: [GNU GPL v3](LICENSE)\n\n## Special Thanks \n\nSpecial thanks to everyone who contributed to and tested **chroot-distro**.\n\n## Faced an Issue?\n\nIf you encounter any problems while using **chroot-distro**, please open an issue [here](https://github.com/Magisk-Modules-Alt-Repo/chroot-distro/issues/).\n\n## Donate \n\nIf you found this project helpful and would like to support the developer, you can donate via Bitcoin:\n\n**Bitcoin Address:** `1LksFFCP2HPdpVsUxfFmZShJFnLLrkZTro`\n","funding_links":[],"categories":["🔧 Development and Debugging"],"sub_categories":["Themes and Visual Mods"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMagisk-Modules-Alt-Repo%2Fchroot-distro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMagisk-Modules-Alt-Repo%2Fchroot-distro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMagisk-Modules-Alt-Repo%2Fchroot-distro/lists"}