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, apart from backports-zstd below Python 3.14, which is what gives the standard library's tarfile zstd support.

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.

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

The password half is a personal access token on most registries, Docker Hub and GHCR included, so export CD_DOCKER_AUTH=myuser:ghp_xxxxxxxx works the same way. The colon is the one thing that is required: a bare token with no username is refused, because the registry needs a name to run the token exchange against.

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

A container for another CPU needs QEMU's user-mode emulator on the host: install qemu-user-static (Linux) or qemu-user-aarch64 and friends (Termux). login then registers it with the kernel's binfmt_misc the first time you enter the container, and the registration stays until the host reboots. chroot-distro info lists which architectures are covered. Nothing to install for your CPU's own 32-bit half: i686 on x86_64 and arm on aarch64 run directly.

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.

Several sessions of one container share its options. A session that joins a container someone is already logged into gets that container's --bind mounts, --shared-* folders and -e/--env values, and whatever it asks for on top is added to the running container, so a second login no longer needs an unmount to bring a folder in. Two exceptions: a --bind whose destination the running container already fills from another source is ignored (with a warning), and --isolated shares nothing, so asking for it while a normal session is running is still an error. CD_USE_NS cannot be turned on for a container that is already running either, and a mismatch there is a warning.

GPU acceleration works on regular Linux with no flag. The render nodes come in with /dev, so an AMD or Intel guest renders with its own Mesa packages, and a host NVIDIA driver's libraries, ICD descriptors and tools are bound in and switched on automatically.

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 is the only way into an image that ships no shell, a scratch image or a distroless one: an interactive session needs a shell the image does not have, so login refuses such a container and points here.

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, kernel support, installed containers, and basic health checks. Attach it when filing a bug report.

It always runs as root, and stops with an error when root cannot be obtained. The kernel support section is probed by trying each feature, not read from a kernel build config, so it reports what the running kernel does.

An image with no base distribution is described rather than flagged. A scratch image and a distroless one ship no shell, so nothing in the rootfs answers the architecture probe: the report reads the architecture out of the image manifest instead and says how the container is started.

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.

Dockerfile support

Every instruction is supported: ADD, ARG, CMD, COPY, ENTRYPOINT, ENV, EXPOSE, FROM, HEALTHCHECK, LABEL, MAINTAINER, ONBUILD, RUN, SHELL, STOPSIGNAL, USER, VOLUME, WORKDIR. So are multi-stage builds with named stages, ARG and ENV expansion, the # escape and # check parser directives, and here-docs.

These fail with a clear error rather than being ignored, because each one would otherwise build something other than what the Dockerfile says:

A # syntax= line naming anything but docker/dockerfile asks for a frontend program that this cannot fetch or run. The build warns and reads the file as an ordinary Dockerfile.

A .dockerignore file in the context excludes files from COPY and ADD, with Docker's own rules: * and ? stop at a /, ** spans any number of folders, ! puts a file back, the last matching line decides, and naming a folder covers everything inside it.

Platforms and output

FROM --platform picks one stage's platform, so FROM --platform=$BUILDPLATFORM builds that stage for your own CPU while the image stays the platform the build targets. An emulator is then only needed for a stage that has a RUN and targets a foreign CPU. TARGETPLATFORM, TARGETOS, TARGETARCH, TARGETVARIANT and the matching BUILD* names are set automatically, and like Docker they live outside the stages: a bare ARG TARGETARCH inside a stage is what lets a RUN there read one.

--platform linux/amd64,linux/arm64 builds one image per platform, one after another, in the order you asked. Two spellings of one platform (linux/arm64 and linux/aarch64) are one image. --architecture names a single platform, so passing both is only allowed when they agree. Each platform is built completely on its own, and if one fails the build stops there and publishes nothing.

Where those images end up:

• --output writes one archive holding an OCI image index over every platform, sharing the layers they have in common. docker load reads the first platform you asked for out of it, since its own format cannot hold more than one; chroot-distro install FILE picks the platform matching your CPU.
• Every --tag records every platform in the local cache, so chroot-distro install myapp:1.0 installs the one for your CPU and chroot-distro install myapp:1.0 -a arm64 the other. chroot-distro push uploads one of them per run, chosen the same way.
• --install-as installs one container, so it takes the platform your device can run. A set of platforms with nothing your device runs is refused before the build starts.

chroot-distro build -t myapp:1.0 --install-as myapp .
chroot-distro build -t myapp:1.0 --platform linux/amd64,linux/arm64 -o myapp.oci.tar .

Cache import and export

build remembers every RUN it executed, but only on the machine that ran it. --cache-to writes what this build's steps produced into a folder, and --cache-from reads such a folder back, so a fresh CI runner can start with the cache the last one finished with.

chroot-distro build -t myapp:1.0 \
    --cache-from type=local,src=.buildcache \
    --cache-to type=local,dest=.buildcache .

type=local is the only kind there is: a plain folder, holding a build-cache.json that lists the steps and a blobs/ folder with one file per layer. Both options can be given more than once.

• Only the steps this build ran are exported, so the folder carries no layer from a build that has nothing to do with it.
• An export adds to what the folder already holds and nothing ever removes anything, so a shared folder only grows. Delete it to start over.
• A folder that is not there yet is not an error: the first build reports that it imported nothing and carries on. A folder that is there and is not a cache folder stops the build.
• Every layer is checked against its own checksums on the way in, and one that does not match is dropped so its step rebuilds. What that cannot check is whether the folder tells the truth about which step a layer belongs to, so point --cache-from only at a folder you trust, the same as with docker buildx.
• --no-cache skips the import, since no step would consult it. The export still runs, and records what the build rebuilt.

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. The password half can be a personal access token, which is what GHCR wants: a token with the write:packages scope in place of the password.

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, which still records what it builds.

A folder written by build --cache-to is yours, not part of this cache, so nothing here touches it. Delete that folder yourself when you want it gone.

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, plus a cache folder that is separate on Linux and nested inside the data folder on Termux:

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:

Inside the cache 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, and a few BuildKit features are rejected with an error.
• push is single-architecture. build --platform produces several platforms at once, but each is pushed on its own with push -a.
• Foreign architectures need the kernel's help. Emulation goes through binfmt_misc, so a kernel built without CONFIG_BINFMT_MISC cannot run an image for another CPU. chroot-distro info reports it.
• Backups capture files only. Running programs are not saved by backup/restore.
• Scratch and distroless images have no shell. They ship no base distribution, so login refuses them and run is how they start: it executes the image's own Entrypoint/Cmd.
• 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.