Chroot-Distro

Chroot-Distro lets you run real Linux systems (Ubuntu, Debian, Alpine, Arch, and more) inside Termux on a rooted Android device, or on any regular Linux machine.

It works in three simple steps: it downloads an image from Docker Hub (or extracts a tarball you give it), unpacks it into a folder, and enters it using the Linux kernel's own chroot and mount features. Because it talks to the kernel directly, everything runs at native speed. It can also build images from a Dockerfile and push them to a registry.

Root access is required. On Termux, the root manager's su is used automatically. On regular Linux, a one-time sudo chroot-distro setup removes all future password prompts.

Table of contents

1. Introduction
2. Commands reference
   • install
   • login
   • run
   • list
   • ps
   • copy
   • sync
   • rename
   • unmount
   • kill
   • reset
   • backup
   • restore
   • diff
   • search
   • setup
   • info
   • help
   • build
   • push
   • clear-cache
   • remove
3. Storage layout
4. Environment variables
5. Limitations
6. Donate

Introduction

Chroot-Distro needs Python 3.10 or newer. It has no third-party dependencies.

Install on Termux (Android)

1. Root your device (Magisk, KernelSU, APatch, or similar).
2. Install Termux from F-Droid or GitHub Releases.
3. Run:

pkg install python
pip install chroot-distro

No sudo or tsu package is needed.

Install on regular Linux

sudo apt install python3-pip   # Debian/Ubuntu example
sudo pip install chroot-distro

Install with sudo (system-wide), not pip install --user. The passwordless daemon runs the code as root, so it refuses user-writable installs.

Passwordless setup (Linux only)

Run this once so you never have to type a password again:

sudo chroot-distro setup

It creates a chroot-distro group, adds you to it, and starts a small root service (works with systemd, OpenRC, runit, dinit, and sysvinit). Log out and back in (or run newgrp chroot-distro) and you are done.

Add more users later with sudo usermod -aG chroot-distro <username>. Remove the service with sudo chroot-distro setup --uninstall.

[!WARNING] Members of the chroot-distro group get root-equivalent access, exactly like the docker group. Only add people you trust.

Quick start

chroot-distro install ubuntu:24.04     # download and install Ubuntu
chroot-distro login ubuntu             # open a shell inside it
chroot-distro list                     # see what is installed
chroot-distro remove ubuntu            # delete it

Commands reference

Every command accepts -h / --help. Run chroot-distro -V to print the version.

install

chroot-distro install [OPTIONS] IMAGE
Aliases: add, i, in, ins

Create a container. IMAGE can be:

For private images, set CD_DOCKER_AUTH first:

export CD_DOCKER_AUTH=myuser:mypassword
chroot-distro install myuser/private-image:tag

Downloaded layers are cached, so installing the same image again works offline.

login

chroot-distro login [OPTIONS] CONTAINER [-- COMMAND ...]
Aliases: sh

Open a shell inside a container. Add -- followed by a command to run that command instead of a shell:

chroot-distro login ubuntu
chroot-distro login ubuntu -- uname -a

If you want namespace isolation but still keep all the normal shared folders, set CD_USE_NS=1 instead of using --isolated.

GPU acceleration (AMD, Intel, NVIDIA) is detected and set up automatically on regular Linux. No flag needed.

run

chroot-distro run [OPTIONS] CONTAINER [-- ARG ...]

Run the start command (Entrypoint/Cmd) defined by the container's image, like docker run. Mainly for server images (nginx, nextcloud, databases). Only works for containers installed from Docker/OCI images.

run accepts all login options above, plus:

chroot-distro run nextcloud
chroot-distro run -d nextcloud

list

chroot-distro list [OPTIONS]
Aliases: li, ls

Show installed containers with their size, image source, and whether they are in use.

ps

chroot-distro ps [OPTIONS]

Show active sessions: PID, container, type (login or run), user, uptime, and command. Detached sessions are marked with *.

copy

chroot-distro copy [OPTIONS] [CONTAINER:]SRC [CONTAINER:]DEST
Aliases: cp

Copy files between the host and a container, or between two containers. Container paths use the name:path form.

Ownership (numeric uid/gid), permissions and timestamps are preserved; --chown sets the owner by name on the destination side instead. Symlinks are copied as symlinks; hardlinks become independent copies; device nodes, FIFOs and sockets are skipped with a warning.

chroot-distro copy ./file.txt ubuntu:/root/file.txt
chroot-distro copy -r ./project ubuntu:/home/user/ --chown user

sync

chroot-distro sync [OPTIONS] [CONTAINER:]SRC [CONTAINER:]DEST

Like copy, but only transfers files that changed. Always recursive. Files are compared by size and modification time.

Ownership, permissions and timestamps are preserved for directories as well as files, and a change to any of them alone is applied without rewriting the file. With --chown the owner it names stands in for the source's, so a destination already carrying it is left alone.

chroot-distro sync ./dotfiles/ ubuntu:/home/user/ --chown user:user

rename

chroot-distro rename OLDNAME NEWNAME

Rename a container.

unmount

chroot-distro unmount CONTAINER
Aliases: umount, um

Cleanly end all sessions of a container and remove its mounts. The gentle version of kill.

kill

chroot-distro kill (CONTAINER | PID)
Aliases: k, stop

Force-stop a running container, like docker kill. Accepts a container name or a session PID from chroot-distro ps. All its processes are terminated and everything is unmounted. Container data is kept.

reset

chroot-distro reset CONTAINER

Wipe a container and reinstall it fresh from its original image. All data inside is lost. Only works for containers installed from Docker/OCI images.

backup

chroot-distro backup [OPTIONS] CONTAINER
Aliases: bak, bkp

Save a container as a TAR archive. Without --output, the archive goes to stdout so you can pipe it.

chroot-distro backup ubuntu -o ubuntu.tar.xz
chroot-distro backup ubuntu | gpg -c > ubuntu.tar.gpg

restore

chroot-distro restore [OPTIONS] [BACKUP_FILE]

Bring back a container from a backup archive. Without a file, it reads from stdin. Compression is detected automatically.

chroot-distro restore ubuntu.tar.xz
gpg -d ubuntu.tar.gpg | chroot-distro restore

diff

chroot-distro diff CONTAINER

Show what changed inside a container compared to its original image, like docker diff. A means added, C changed, D deleted. Needs the image layers to still be in the cache, so avoid clear-cache if you want diff to keep working.

search

chroot-distro search [OPTIONS] TERM
Aliases: find, se

Search Docker Hub. Shows image name, stars, official status, and a short description.

setup

chroot-distro setup [OPTIONS]

One-time passwordless setup on regular Linux. See Passwordless setup. Not needed on Termux.

info

chroot-distro info
Aliases: version-info, nf

Print a diagnostics report: versions, device details, host capabilities, installed containers, and basic health checks. Attach it when filing a bug report.

help

chroot-distro help [COMMAND]
Aliases: h, he, hel

Show detailed help for a command, or general usage when no command is given.

build

chroot-distro build [OPTIONS] [PATH]

Build an image from a Dockerfile, like docker build but without Docker. PATH is the folder with your Dockerfile (default: current folder). The result is stored locally, so chroot-distro install <tag> installs it offline.

RUN steps need root because they execute inside the half-built image. RUN --mount with type=bind, cache, tmpfs, secret, and ssh is supported. RUN --network=none, RUN --security, COPY --link, and COPY --parents are not, and fail with a clear error.

chroot-distro build -t myapp:1.0 --install-as myapp .

push

chroot-distro push [OPTIONS] IMAGE

Upload an image you built with build -t to Docker Hub or another registry. Layers already on the registry are skipped.

Set CD_DOCKER_AUTH=username:password before pushing to a private repository.

clear-cache

chroot-distro clear-cache [OPTIONS]
Aliases: clear, cl

Delete all cached downloads (image layers, manifests, build cache) and show how much space was freed. After this, installing an image needs the network again, and diff stops working for existing containers.

Every RUN a build executes is recorded against the layer it produced, so a later build with the same parent, instruction and inputs reuses it. Nothing ever evicts those entries, and every edit to a Dockerfile strands the ones before it, so the build cache is the part that only grows.

# Reclaim the build cache, keep the downloaded images
chroot-distro clear-cache --build-cache

This removes the index and then deletes the layers nothing else points at. The layers of images you still have are kept, so what goes is the build's own bookkeeping, the intermediates no image held on to, and any leftover blob from a killed download. The next build re-runs every step. It refuses to run while another chroot-distro command holds a lock, since a build in progress has recorded steps whose layers this would unpin. To skip cache lookups for a single build without deleting anything, use build --no-cache instead — note that it still records what it builds.

remove

chroot-distro remove [OPTIONS] CONTAINER
Aliases: rm

Delete a container and all its data. There is no confirmation and no undo. Active sessions are unmounted first.

Storage layout

Everything lives in one data folder:

On regular Linux, commands run as root, so the folders are usually under /root/ unless you set XDG_DATA_HOME / XDG_CACHE_HOME.

Inside the data folder:

Environment variables

All of these are optional.

Limitations

• Root is required. The kernel's chroot and mount features need it. There is no rootless mode, and no support for non-rooted Android.
• Network is shared with the host by design. Containers use your Wi-Fi, mobile data, and VPN directly. There is no network isolation, even with --isolated.
• GPU is shared by design. GPU access is automatic whenever supported hardware is detected.
• No full init systems. systemd and similar will not work inside containers. Individual long-running programs are fine.
• Isolation is partial. --isolated covers mount, PID, UTS, and IPC namespaces. It is not a full container runtime like Docker or Podman.
• Builds are not full BuildKit. RUN steps execute under chroot. A few BuildKit features are rejected with an error, and multi-platform images are not produced.
• push is single-architecture. Build and push once per CPU type.
• Backups capture files only. Running programs are not saved by backup/restore.
• Registry login is env-var only. Set CD_DOCKER_AUTH. Docker's config.json credential helpers are not read.

Donate

If this project is useful to you, tips in cryptocurrency are welcome:

Bitcoin

13Q7xf3qZ9xH81rS2gev8N4vD92L9wYiKH

Ethereum / USDT (BEP20, ERC20)

0x1d216cf986d95491a479ffe5415dff18dded7e71

USDT (TRC20)

TCjRKPLG4BgNdHibt2yeAwgaBZVB4JoPaD

Dogecoin

DJkMCnBAFG14TV3BqZKmbbjD8Pi1zKLLG6

Issues and contributing

• Bug reports: https://github.com/sabamdarif/chroot-distro/issues
• License: GPL-3.0-only. See LICENSE.

Acknowledgments

• proot-distro - cli design, inspiration, and a lot more. Commands and syntax are intentionally kept close to proot-distro's so the experience feels familiar, and substantial parts of the implementation are ported directly from it and adapted to fit this project.
• pyLoad — downloader improvements.
• distrobox - shared-display option improvements.
• Magisk-Modules-Alt-Repo/chroot-distro - some info about chroot on android.
• ravindu644/Ubuntu-Chroot - some info about chroot on android.