Chroot-Distro is a utility for managing rootful Linux containers in
Termux and on regular Linux hosts. It uses the
host kernel's native chroot and bind mounts (mount --bind) to provide a
high-performance, near-native Linux environment.
Containers are created by pulling Docker/OCI images directly from Docker Hub or any compatible registry — or by extracting a local tarball / OCI image archive. The container filesystem is assembled from the image layers and stored locally, ready to be entered at any time.
Chroot-Distro can also build OCI images from a Dockerfile (no Docker daemon required), storing the result in the local manifest cache or exporting it as a standalone OCI tarball.
Unlike proot-distro (which is
rootless via proot), Chroot-Distro requires root privileges on the host. Mutating commands
automatically re-launch themselves via sudo, doas, pkexec, or su
when needed (see First-run check).
- Introduction
- Commands reference
- How Chroot-Distro works
- Storage layout
- Environment variables
- Shell completions
- Limitations
- Donate
Chroot-Distro lets you run a full Linux userland — Ubuntu, Debian,
Alpine, Arch, openSUSE, distroless server images, anything available as
a Docker/OCI image — on top of Termux on a rooted Android device, or on
top of a regular Linux distribution, with native kernel performance,
without the overhead of proot's ptrace interception, and
without a Docker daemon.
Typical use cases:
- Running a desktop-class Linux distribution on a phone or tablet at near-native speed (rooted device required on Termux).
- Disk-intensive and compile workloads (GCC/Clang, Rust, Go) without
prootslowdowns. - Spinning up server software (Nginx, Nextcloud, PostgreSQL, etc.) on Android by reusing the same OCI images you'd run on a server.
- Building custom OCI images from a Dockerfile on-device, without a Docker daemon — and pushing them to Docker Hub, GHCR, or any OCI-compatible registry.
- Trying a distribution non-destructively: install, experiment,
chroot-distro removewhen done.
Chroot-Distro requires Python 3.10 or newer. There are no third-party
Python dependencies. Because it uses native chroot and bind mounts, the
effective user for mutating operations must be root (see
First-run check).
- Root your device (Magisk, KernelSU, APatch, or similar).
- Install Termux from F-Droid or Termux GitHub Releases.
- Install Chroot-Distro:
pkg install coreutils sudo python mount-utils
pip install chroot-distroFrom a local checkout:
git clone https://github.com/sabamdarif/chroot-distro
cd chroot-distro
pip install . # regular install
# pip install -e . # editable install for development# Debian/Ubuntu example:
sudo apt install python3-pip
pip install chroot-distro
# or from a checkout:
git clone https://github.com/sabamdarif/chroot-distro
cd chroot-distro
pip install .On startup, commands that modify containers or mounts verify that the
effective UID is 0. If not, Chroot-Distro re-executes itself using, in
order: sudo, doas, pkexec, or su.
| Situation | Behaviour |
|---|---|
| Default | Auto-elevate when not root. |
--no-elevate or CHROOT_DISTRO_NO_ELEVATE=1 |
Skip elevation; exit with an error if not root. |
| Termux, default | Prefer su (real root) over sudo. |
Termux, --use-sudo or CHROOT_DISTRO_USE_SUDO=1 |
Prefer sudo for elevation. |
list, ps, search, and help do not require root and are never
re-executed.
# Install Ubuntu 24.04 from Docker Hub
chroot-distro install ubuntu:24.04
# Start a shell inside the container
chroot-distro login ubuntu
# Same thing, using the login alias
chroot-distro sh ubuntu
# Run a single command and exit
chroot-distro login ubuntu -- /bin/uname -a
# List all installed containers
chroot-distro list
# Build and install a custom image from a Dockerfile
chroot-distro build -t myapp:1.0 --install-as myapp ./mycontext
# Publish the built image to a registry
export CD_DOCKER_AUTH=myuser:mypassword
chroot-distro push myuser/myapp:1.0
# Rebuild from scratch (loses all in-container data)
chroot-distro reset ubuntu
# List only the containers that are currently running
chroot-distro ps
# Search Docker Hub for an image
chroot-distro search nextcloud
# See what changed in a container relative to its image
chroot-distro diff ubuntu
# Unmount bindings and end active sessions
chroot-distro unmount ubuntu
# Forcibly stop a running container (SIGKILL + unmount)
chroot-distro kill ubuntu
# Permanently remove a container (unmounts active sessions first)
chroot-distro remove ubuntuEvery subcommand supports --help (also -h), which prints help text
laid out for the current terminal width.
Global flags (before the subcommand):
| Option | Description |
|---|---|
-h, --help |
Show top-level help. |
--no-elevate |
Do not auto-elevate to root (CHROOT_DISTRO_NO_ELEVATE=1). |
--use-sudo |
On Termux, prefer sudo over su (CHROOT_DISTRO_USE_SUDO=1). |
Short aliases are accepted for many commands (sh → login, rm →
remove, ins → install, etc.); each section below lists them.
chroot-distro install [OPTIONS] (IMAGE or PATH or URL)
Aliases: add, i, in, ins
Pull a Docker/OCI image and create a container from it, extract a local archive, or download a remote archive over HTTP/HTTPS.
Options:
| Option | Description |
|---|---|
-n, --name NAME |
Custom local container name. Defaults to the image name (without tag/registry) or the archive filename. Must start with a letter or digit; may contain only letters, digits, _, ., -. |
--override-alias NAME |
Same as -n / --name (mutually exclusive). |
-a, --architecture ARCH |
Override target CPU architecture. Accepts native names (aarch64, arm, i686, riscv64, x86_64) or Docker platform strings (linux/arm64, linux/amd64, …). Defaults to the host CPU. |
-q, --quiet |
Suppress non-error output. |
IMAGE is a standard Docker image reference:
| Form | Example |
|---|---|
| Official image | ubuntu:24.04 |
Official, no tag (uses latest) |
alpine |
| User image | myuser/myimage:tag |
| Custom registry | ghcr.io/foo/bar:latest |
Custom registries are detected when the first path component contains
. or : (a hostname). Public images on ghcr.io, quay.io,
registry.gitlab.com, etc. are pulled with an anonymous Bearer token
discovered from each registry's /v2/ challenge.
Private images require credentials. Set CD_DOCKER_AUTH to
username:password (or username:PAT) before running install. The
colon separator is mandatory. PD_DOCKER_AUTH is accepted as a fallback
for compatibility with proot-distro:
export CD_DOCKER_AUTH=myuser:mypassword
chroot-distro install myuser/private-image:tag
export CD_DOCKER_AUTH=myuser:ghp_xxx
chroot-distro install ghcr.io/myorg/private-image:tagLayers are cached under $BASE_CACHE_DIR/oci_layers/ and reused on
subsequent installs. If the resolved manifest and all layers are already
cached, installation runs fully offline.
Missing layers are downloaded in parallel (default 4 workers). Set
CD_DOWNLOAD_WORKERS to tune concurrency (integer 1–10; values above
10 are capped).
On Termux, list does not elevate privileges. If containers were
installed as root, run once as root to fix legacy manifest permissions:
su -c 'chmod -R a+r $PREFIX/var/lib/chroot-distro/containers/*/manifest.json'
(or reinstall). New installs write manifest.json as world-readable
(0644).
Examples:
chroot-distro install ubuntu:24.04
chroot-distro install alpine:3.21 --name my-alpine
chroot-distro install debian:bookworm --architecture aarch64
chroot-distro install ghcr.io/myorg/myimage:latestIMAGE can be a path starting with /, ./, ../, or ~. A bare
token like ubuntu is always treated as a Docker image reference.
Two archive formats are supported (auto-detected):
- Plain rootfs tarball — top-level entries form a standard Linux
filesystem (
bin/,etc/,usr/, …). Strip level is scored automatically. Compression: gzip, bzip2, xz, lzma, or uncompressed. Nomanifest.jsonis written (resetandrunare not available). - OCI image layout — archive contains
oci-layoutat its root (as fromdocker saveorskopeo copy oci-archive:). Layers are applied with OCI whiteout semantics;manifest.jsonis written soresetandrunwork like registry installs.
Examples:
chroot-distro install ./alpine-rootfs.tar.gz
chroot-distro install ./myimage.oci.tar --name myimageWhen an HTTP or HTTPS URL is given instead of a local path, the archive
is downloaded fully and then processed the same way as a local file.
Only http:// and https:// are supported. The default container name
is derived from the last URL path component; use --name to override.
chroot-distro install https://example.com/rootfs.tar.xz --name demoAfter installation, if the image defines an Entrypoint, a
Run entrypoint: chroot-distro run <name> hint is printed alongside
Start shell: chroot-distro login <name>.
chroot-distro build [OPTIONS] [PATH]
Build an OCI/Docker-compatible image from a Dockerfile. PATH is the
build context directory (default .); all COPY/ADD source paths are
resolved relative to it.
By default the built image is stored in the local manifest cache under
the tag given by --tag (default <basename(PATH)>:latest). A subsequent
chroot-distro install <tag> installs entirely without network access.
Options:
| Option | Description |
|---|---|
-f, --file PATH |
Dockerfile at PATH instead of <PATH>/Dockerfile. Pass - to read from stdin. |
-t, --tag REF |
Image reference to assign. Repeatable. |
--build-arg K=V |
Set a build-time ARG (only declared ARGs are honoured). Repeatable. |
--architecture ARCH |
Target CPU architecture (default: host). |
--target STAGE |
Stop after the named multi-stage build stage. |
-o, --output FILE |
Write an OCI image-layout tarball to FILE. Compression inferred from the extension. Repeatable. |
--install-as NAME |
After build, install the image as container NAME. |
--no-cache |
Disable per-step build caching. |
-v, --verbose |
Echo each instruction and stream RUN output. |
-q, --quiet |
Suppress non-error output. |
Supported Dockerfile instructions:
FROM (multi-stage, FROM scratch, COPY --from=), RUN (shell,
JSON exec, here-doc), COPY (--from, --chown, --chmod), ADD,
CMD, ENTRYPOINT, ENV, ARG, LABEL, MAINTAINER, USER,
WORKDIR, EXPOSE, VOLUME, STOPSIGNAL, HEALTHCHECK, SHELL,
ONBUILD.
BuildKit-only features (RUN --mount, RUN --network,
RUN --security, COPY --link, COPY --parents) are rejected with an
explicit error.
chroot requirement:
If the Dockerfile contains any RUN instruction, each step executes
inside the in-progress rootfs via chroot and therefore requires root.
Metadata-only builds (COPY/ADD/ENV/… without RUN) run in
pure-Python mode and do not require root.
Examples:
chroot-distro build .
chroot-distro build -t myapp:1.0 --install-as myapp .
chroot-distro build -t myapp:arm64 --architecture aarch64 -o myapp.oci.tar.gz .
chroot-distro build --build-arg HTTP_PROXY=$HTTP_PROXY -t myapp .Limitations:
RUN steps run under chroot, not a real container runtime: no PID,
network, or IPC isolation, no cgroups, no seccomp. Steps that depend
on real namespaces or kernel features may fail or behave differently from
docker build. Multi-platform manifest lists are not produced.
chroot-distro push [OPTIONS] IMAGE
Upload a locally built image to a Docker/OCI registry. The image must
have been produced by chroot-distro build -t IMAGE first; push reads
the manifest and blobs from the local cache. No Docker daemon is
required.
Options:
| Option | Description |
|---|---|
--architecture ARCH |
Push the manifest built for the given architecture (must match the build). Default: host. |
-q, --quiet |
Suppress non-error output. |
Authentication:
Set CD_DOCKER_AUTH=username:password (colon required). PD_DOCKER_AUTH
is accepted as a fallback:
chroot-distro build -t myuser/myapp:1.0 ./mycontext
export CD_DOCKER_AUTH=myuser:mypassword
chroot-distro push myuser/myapp:1.0Each layer is HEAD-probed first; existing blobs are skipped. 401/403
responses include a hint to set or fix CD_DOCKER_AUTH.
chroot-distro login [OPTIONS] CONTAINER [-- COMMAND ...]
Aliases: sh
Spawn an interactive shell (or a custom command) inside an installed
container. The -- separator passes arguments to the container's login
shell.
Examples:
chroot-distro login ubuntu
chroot-distro login ubuntu --user myuser
chroot-distro login ubuntu -- /bin/ls /etc
chroot-distro login ubuntu -- bash -c "echo hello"
chroot-distro sh ubuntu
chroot-distro login ubuntu --get-chroot-cmdOptions always available:
| Option | Description |
|---|---|
-u, --user USER |
Log in as USER (default: root). Accepts name, numeric uid, name:group, or uid:gid. |
--isolated |
Reduce host exposure and enable namespace isolation (mount, PID, UTS, IPC via unshare/nsenter). On Termux: also skip Android system, storage, and $PREFIX binds unless you opt in with --shared-* or --bind. On Linux: skip default /tmp unless --shared-tmp. Mutually exclusive with --minimal. |
--minimal |
Bare minimum chroot: core pseudo-filesystems only (/dev, /proc, /sys, plus /run, /dev/pts, /dev/shm when present). Stripped guest environment. Mutually exclusive with --isolated. |
--shared-home |
Bind the invoking user's host home into the guest home (or /root for root). On Termux, binds TERMUX_HOME. |
--shared-tmp |
Bind host tmp (/tmp on Linux, $PREFIX/tmp on Termux) to /tmp in the guest. On Linux, included by default unless --isolated. |
--shared-display |
Share the host display server (X11 and Wayland), audio (PulseAudio/PipeWire), and D-Bus session bus with the container. Opt-in only. --shared-x11 is accepted as a backward-compatible alias. |
-b, --bind SRC[:DST] |
Bind-mount a custom host path (repeatable). DST must be an absolute guest path. |
--hostname STRING |
Hostname inside the container (default: localhost). |
-w, --work-dir PATH |
Initial working directory (default: user's home). |
-e, --env VAR=VALUE |
Set a guest environment variable (repeatable). |
--get-chroot-cmd |
Print the fully assembled env + chroot command line and exit. |
Display sharing is active when using --shared-display (or --shared-x11 as a backward-compatible alias).
It work best on regular Linux and in Termux it doesn't have all the options
Display sharing forwards four subsystems from the invoking host session into the container:
X11
/tmp/.X11-unixsocket directory is bind-mounted into the guest.DISPLAY,XAUTHORITY, andXDG_RUNTIME_DIRare forwarded.- The X authority file is bind-mounted when it lives outside
/run. - Compositors such as niri with xwayland-satellite often authenticate X11
clients by Unix-socket UID. Chroot-distro aligns the guest user's UID to
the invoking host user when needed. If the guest cannot read the cookie
file, it is copied to
/var/tmp/.chroot-distro-xauthority(requiresxauthon the host). If that fails, use--shared-home,xhost +SI:localuser:GUEST, or a UID-matched user.
Wayland
WAYLAND_DISPLAYis forwarded (fallback:wayland-0if socket exists).XDG_SESSION_TYPE,XDG_CURRENT_DESKTOP, andDESKTOP_SESSIONare forwarded from the host session.- Host
/runis bind-mounted with rslave propagation so new Wayland compositor sockets created after mount are immediately visible inside the container.
Sound (PulseAudio / PipeWire)
PULSE_SERVERis forwarded (fallback:unix:/run/user/<uid>/pulse/nativeif the PulseAudio socket exists).- PipeWire apps discover their socket automatically via
XDG_RUNTIME_DIR; no extra env var is needed.
D-Bus
DBUS_SESSION_BUS_ADDRESSis forwarded (fallback:unix:path=/run/user/<uid>/busif the socket exists).
Use --isolated to skip all display sharing, or --minimal for only core
pseudo-filesystems. Home is never bind-mounted unless you pass --shared-home.
Chroot-distro automatically enables hardware-accelerated GPU rendering at
login if use --shared-display. (It doesn't work on Termux)
AMD and Intel (open-source Mesa drivers)
- Works out of the box. Host
/dev(including/dev/dri/render nodes) is bind-mounted into the container. Guest Mesa drivers access GPU hardware directly — no extra configuration needed.
NVIDIA — native Linux (proprietary driver)
- Detection:
/dev/nvidia0exists, orlibcuda*.so*/libnvidia*.so*found under/usr/lib*/. - Bind-mounts:
/dev/nvidia*device nodes,/dev/dri/card*and/dev/dri/renderD*DRM nodes, host NVIDIA.solibraries mapped to the correct guest library directory (multi-arch aware), NVIDIA config and ICD files (/etc/, EGL/Vulkan JSON descriptors, OpenCL ICD), and NVIDIA CLI tools (nvidia-smi, etc.). - Environment variables set:
__NV_PRIME_RENDER_OFFLOAD=1,__GLX_VENDOR_LIBRARY_NAME=nvidia. - Guest
ldconfigis run inside the chroot to refresh the shared library cache after the new libraries are bind-mounted.
With --isolated, chroot-distro creates a per-container namespace holder
(unshare) and runs bind mounts, special mounts, and chroot inside that
environment (nsenter). Supported namespaces: mount, PID, UTS,
and IPC (each is used only if the kernel supports it; mount is
required). This is inspired by Ubuntu-Chroot
and is not a full container runtime: there is no network namespace, no
user namespace mapping, and no image layering.
Do not mix --isolated and non-isolated logins on the same container
without running chroot-distro unmount <name> first. Concurrent
--isolated sessions share the same holder and mounts.
Without --isolated or --minimal, the following host paths are
bind-mounted when present and readable:
/apex
/data/app
/data/dalvik-cache
/data/misc/apexdata/com.android.art/dalvik-cache
/data/data/<termux-app-package>
/linkerconfig/com.android.art/ld.config.txt
/linkerconfig/ld.config.txt
/odm
/plat_property_contexts
/product
/property_contexts
/sdcard
/storage/emulated/0
/storage/self/primary
/system
/system_ext
/vendor
For normal-type containers, the Termux $PREFIX is also bound at its
original path so Termux utilities (termux-api, pkg, etc.) remain
reachable inside the guest.
The host environment is not carried into the guest. Precedence (later entries win):
- Baseline:
PATH(fromDEFAULT_PATH_ENV),MOZ_FAKE_NO_SANDBOX=1,PULSE_SERVER=127.0.0.1(Termux only). - Image-defined
Envfrommanifest.json(display and GPU vars are blocked here — they are always set by auto-detection). - Android system vars (
ANDROID_*,BOOTCLASSPATH, …), Termux only, when not--isolatedand not--minimal. - Your
--env VAR=VALUEentries. HOME,USER,TERM(defaultxterm-256color),COLORTERM(when set on the host).- When display sharing is active (via
--shared-display):DISPLAY,XAUTHORITY,XDG_RUNTIME_DIR,WAYLAND_DISPLAY,XDG_SESSION_TYPE,XDG_CURRENT_DESKTOP,DESKTOP_SESSION,PULSE_SERVER,DBUS_SESSION_BUS_ADDRESS. Your--enventries override these. - On Linux (unless
--minimal): GPU env vars when NVIDIA is auto-detected: native —__NV_PRIME_RENDER_OFFLOAD,__GLX_VENDOR_LIBRARY_NAME; WSL2 —GALLIUM_DRIVER,MESA_D3D12_DEFAULT_DEVICE_TYPE,LIBGL_ALWAYS_SOFTWARE. Your--enventries override these.
On Termux (unless isolated or minimal), $PREFIX/bin is appended to
PATH. A snippet at /etc/profile.d/termux-profile.sh re-applies
login-time variables after the distro's /etc/profile runs, so
su - someuser inside the container does not drop them.
In --minimal mode only your --env entries plus TERM/COLORTERM
are exported.
The first login or run for a container performs bind mounts and
increments a session counter. Each exiting session decrements it; when
the counter reaches zero, all bind mounts are unmounted automatically.
Use unmount to force teardown (see below).
chroot-distro run [OPTIONS] CONTAINER [-- ARG ...]
Run the Entrypoint and/or Cmd from the container's OCI manifest
(equivalent to docker run). Requires an OCI install with
manifest.json (plain tarball installs have no recorded
Entrypoint/Cmd).
Entrypoint and Cmd resolution:
| Image | Args after -- |
Inner command |
|---|---|---|
Entrypoint + Cmd |
(none) | Entrypoint + Cmd |
Entrypoint + Cmd |
ARGS |
Entrypoint + ARGS (Cmd replaced) |
Only Cmd |
(none) | Cmd |
Only Cmd |
ARGS |
ARGS (Cmd replaced) |
Only Entrypoint |
(none) | Entrypoint |
Only Entrypoint |
ARGS |
Entrypoint + ARGS |
| Neither | (none) | Error |
| Neither | ARGS |
ARGS |
When --work-dir is not given, run uses the image WorkingDir
(falling back to /).
run accepts the same options as login. See
chroot-distro login --help.
Examples:
chroot-distro run hello-world
chroot-distro run ubuntu -- /bin/echo hi
chroot-distro run nextcloud --get-chroot-cmdchroot-distro list [OPTIONS]
Aliases: li, ls
Show installed containers (subdirectories of containers/ with a
rootfs/). For each container prints rootfs size, image source
(Docker/OCI reference and architecture from manifest.json, or
local archive for plain tarballs), and status (idle or
in use with PID when another command holds the container lock).
Does not require root. When none are installed, an install suggestion is
printed.
| Option | Description |
|---|---|
-q, --quiet |
Print only container names, one per line. |
chroot-distro ps [OPTIONS]
List only containers that are currently running — those with a live
process inside their chroot or an active namespace holder. Columns match
list (rootfs size, image source, status). Does not require root.
| Option | Description |
|---|---|
-a, --all |
Show all installed containers, not just running ones. |
-q, --quiet |
Print only container names, one per line. |
chroot-distro search [OPTIONS] TERM
Aliases: find, se
Search Docker Hub for images matching TERM and print the image name,
star count, whether it is an official image, and a short description.
Uses a single unauthenticated request to the Docker Hub search API.
Requires network access; does not require root.
| Option | Description |
|---|---|
-l, --limit N |
Maximum number of results to show (default 25, max 100). |
Examples:
chroot-distro search nextcloud
chroot-distro search --limit 50 ubuntuchroot-distro diff CONTAINER
Inspect changes to files and directories in a container's filesystem
relative to the OCI/Docker image it was installed from (like
docker diff). The image baseline is reconstructed from the cached OCI
layers, then compared against the live rootfs. Output uses Docker-style
markers:
| Marker | Meaning |
|---|---|
A |
File or directory was added |
C |
File or directory was changed |
D |
File or directory was deleted |
Pseudo-filesystem mount points (/dev, /proc, /sys, /run, /tmp)
are excluded. Available only for containers installed from an image whose
layers are still present in the cache (avoid clear-cache to keep diff
working).
chroot-distro remove [OPTIONS] CONTAINER
Aliases: rm
Permanently delete the container and all its data. This cannot be undone and is not confirmed.
Before deletion, active mounts are detected via /proc/mounts and
unmounted cleanly. File permissions are fixed on the fly so chmod-000'd
subtrees can always be removed.
| Option | Description |
|---|---|
-v, --verbose |
Log each deleted file. |
-q, --quiet |
Suppress non-error output. Mutually exclusive with --verbose. |
chroot-distro unmount CONTAINER
Aliases: umount, um
Safely unmount a container's bind mounts. If chroot processes are still
running, SIGTERM is sent (with SIGKILL after two seconds if needed),
the session counter is reset to 0, and all bind mounts are removed.
If a path is busy, a lazy unmount (umount -l) is attempted as a
fallback.
chroot-distro kill CONTAINER
Aliases: k, stop
Forcibly stop a running container: all processes inside its chroot are
sent SIGTERM and then SIGKILL after a short grace period, the bind
mounts are unmounted, and the namespace holder (if any) is released. This
is the abrupt counterpart to unmount (equivalent to docker kill).
chroot-distro rename OLDNAME NEWNAME
Rename a container from OLDNAME to NEWNAME.
| Option | Description |
|---|---|
-q, --quiet |
Suppress non-error output. |
chroot-distro reset CONTAINER
Remove the container rootfs and reinstall from the image recorded in
containers/<name>/manifest.json. All data inside the container is
lost. Requires an OCI install (plain rootfs tarballs cannot be
re-pulled).
| Option | Description |
|---|---|
-q, --quiet |
Suppress non-error output. |
chroot-distro backup [OPTIONS] CONTAINER
Aliases: bak, bkp
Create a TAR archive containing <name>/manifest.json (when present)
and <name>/rootfs/.
Options:
| Option | Description |
|---|---|
-o, --output FILE |
Write to FILE instead of stdout. Refuses to overwrite an existing file. |
-c, --compress TYPE |
Force compression: gzip, bzip2, xz, or none. |
-v, --verbose |
Log each archived file. |
-q, --quiet |
Suppress non-error output. Mutually exclusive with --verbose. |
Compression is inferred from the file extension unless --compress
overrides it. Without --output, the archive goes to stdout
(uncompressed by default); stdout cannot be a TTY.
File ownership in the archive is zeroed. Block/char devices, FIFOs, and
sockets are skipped. backup is TTY-safe when piping into
interactive tools (e.g. gpg -c).
Examples:
chroot-distro backup ubuntu --output ubuntu.tar.xz
chroot-distro backup ubuntu | gzip > ubuntu.tar.gz
chroot-distro backup ubuntu | gpg -c > ubuntu.tar.gpgchroot-distro restore [OPTIONS] [BACKUP_FILE]
Restore from a TAR archive. When BACKUP_FILE is omitted, data is read
from stdin. Compression is auto-detected.
Options:
| Option | Description |
|---|---|
-v, --verbose |
Log each extracted file. |
-q, --quiet |
Suppress non-error output. Mutually exclusive with --verbose. |
Archive format requirements:
- Files must live under
<name>/manifest.jsonand<name>/rootfs/…. Bare-root archives are rejected. - Without
manifest.json, login still works butresetandrunwill not. - Hard links in the archive are materialised as independent copies.
restore is TTY-safe for interactive pipelines
(gpg -d archive.gpg | chroot-distro restore).
Examples:
chroot-distro restore ubuntu.tar.xz
cat ubuntu.tar.xz | chroot-distro restore
gpg -d ubuntu.tar.gpg | chroot-distro restorechroot-distro copy [OPTIONS] [CONTAINER:]SRC [CONTAINER:]DEST
Aliases: cp
Copy files between the host and a container rootfs, or between two
containers. In-container paths use the container:path prefix.
| Option | Description |
|---|---|
-r, --recursive |
Copy directories recursively (preserves symlinks). |
-m, --move |
Move instead of copy (delete source after success). |
-v, --verbose |
Log each copied file. |
-q, --quiet |
Suppress non-error output. Mutually exclusive with --verbose. |
Examples:
chroot-distro copy ./file.txt ubuntu:/root/file.txt
chroot-distro copy ubuntu:/etc/resolv.conf ./resolv.conf.bak
chroot-distro copy --recursive ./myapp ubuntu:/opt/myappchroot-distro sync [OPTIONS] [CONTAINER:]SRC [CONTAINER:]DEST
Synchronize SRC to DEST, copying only files that differ. Always recursive.
Comparison method:
| Mode | What is compared |
|---|---|
| Default | File size and integer modification time |
--checksum |
File size and CRC32 checksum |
Regular files are written atomically (.~cd_sync temp file →
os.replace). Symlinks are copied as-is. Hard links become independent
copies. Block/char devices, FIFOs, and sockets are skipped.
| Option | Description |
|---|---|
-c, --checksum |
Compare by size + CRC32 instead of size + mtime. |
-d, --delete |
Remove destination entries with no source counterpart. |
-v, --verbose |
Log each synced or deleted entry. |
-q, --quiet |
Suppress non-error output. Mutually exclusive with --verbose. |
Examples:
chroot-distro sync ./app ubuntu:/opt/app
chroot-distro sync --checksum ./data ubuntu:/data
chroot-distro sync --delete ./app ubuntu:/opt/appchroot-distro clear-cache
Aliases: clear, cl
Remove every entry from $BASE_CACHE_DIR — layer blobs (oci_layers/),
resolved manifests (oci_manifests/), and the build cache index
(build_cache_index.json). Freed disk space is reported in human-readable
units.
| Option | Description |
|---|---|
-v, --verbose |
Log each deleted file. |
-q, --quiet |
Suppress non-error output. Mutually exclusive with --verbose. |
After clear-cache, the next install or reset of an image requires
network access again.
chroot-distro help [COMMAND]
Aliases: h, he, hel
Print detailed help for COMMAND, or general usage when omitted.
Chroot-Distro is a thin orchestration layer around two primary building blocks:
The install command speaks the OCI Distribution protocol directly over
urllib:
- Public images on Docker Hub need no credentials
(e.g.
ubuntu:24.04). - Public images on other registries use a full reference
(e.g.
ghcr.io/myorg/myimage:tag). - Manifest lists are resolved to the platform matching your CPU (or
--architecture). - Each layer blob is downloaded with SHA-256 verified before entering the cache.
- Layer blobs and the resolved single-arch manifest are cached locally.
Layers are applied in order with full OCI whiteout semantics. After all
layers are applied, Chroot-Distro adds small fixups when /etc/ exists:
/etc/resolv.confis replaced with Google DNS (8.8.8.8 / 8.8.4.4)./etc/hostsgets a minimal localhost mapping.- On Termux, the host Android user is registered as
aid_<name>in/etc/passwd,/etc/group, etc., so Android UID permissions work inside the guest.
The OCI manifest and image config are saved to
containers/<name>/manifest.json for reset and run.
Local archives and HTTP/HTTPS URLs follow the same extraction paths as
in the install section.
Unlike proot, which rewrites paths via ptrace, Chroot-Distro uses
real kernel features:
- Bind mounts (
mount --bind) for host directories inside the guest. - Session tracking under
$RUNTIME_DIR/data/<name>/sessions. - Automatic mount/unmount: the first session mounts; the last session exiting unmounts everything.
- Lazy unmount fallback (
umount -l) when a target is busy.
A typical login invocation looks roughly like:
env PATH=… HOME=/root USER=root … \
chroot /…/containers/ubuntu/rootfs \
/bin/sh -c 'cd /root && exec /bin/bash -l'Add --get-chroot-cmd to print the exact command line without running it.
Guest architectures (aarch64, arm, i686, x86_64, riscv64) are
detected at login by reading ELF headers of common shell binaries. Cross-arch
execution uses QEMU user-mode via binfmt_misc / QEMU user binaries
installed on the host.
All runtime data lives under $RUNTIME_DIR:
- Termux:
$TERMUX__PREFIX/var/lib/chroot-distro/, whereTERMUX__PREFIXdefaults to/data/data/com.termux/files/usr. - Regular Linux:
$XDG_DATA_HOME/chroot-distro/(default~/.local/share/chroot-distro/).
The OCI cache ($BASE_CACHE_DIR) is under $RUNTIME_DIR/cache on
Termux, and under $XDG_CACHE_HOME/chroot-distro/ (default
~/.cache/chroot-distro/) on a regular Linux host.
Because mutating commands run as root after auto-elevation, effective
paths on Linux are typically under /root/.local/share/ and
/root/.cache/ unless you set XDG_DATA_HOME / XDG_CACHE_HOME.
| Path | Contents |
|---|---|
containers/<name>/rootfs/ |
Container root filesystem |
containers/<name>/manifest.json |
Image reference, arch, OCI manifest, image config |
data/<name>/sessions |
Active login / run session counter |
locks/<name>.lock |
Per-container POSIX flock |
locks/build/<key>.lock |
Build/push lock |
$BASE_CACHE_DIR/oci_layers/ |
Cached OCI layer blobs |
$BASE_CACHE_DIR/oci_manifests/ |
Cached single-arch manifests |
$BASE_CACHE_DIR/build_cache_index.json |
Dockerfile build cache index |
| Variable | Effect |
|---|---|
TERMUX__PREFIX |
Override Termux prefix; drives RUNTIME_DIR on Termux. Default: /data/data/com.termux/files/usr. |
TERMUX__HOME |
Override Termux home for --shared-home bindings. Default: /data/data/com.termux/files/home. |
TERMUX_APP__PACKAGE_NAME |
Termux app package (default com.termux); used for /data/data/<pkg>/… binds. |
TERMUX_APP__APP_VERSION_NAME, TERMUX_VERSION |
Either counts toward Termux detection when set. |
XDG_DATA_HOME |
Base for $XDG_DATA_HOME/chroot-distro/ on non-Termux hosts. Default: ~/.local/share. |
XDG_CACHE_HOME |
Base for $XDG_CACHE_HOME/chroot-distro/ on non-Termux hosts. Default: ~/.cache. |
CD_DOCKER_AUTH |
Registry credentials as username:password or username:PAT (colon required). Used by install, build (FROM pulls), and push. PD_DOCKER_AUTH is accepted as a fallback. |
CD_DOWNLOAD_WORKERS |
Parallel registry layer downloads during install (default 4, maximum 10). Invalid values use the default; out-of-range values are clamped. |
CD_DOWNLOAD_RATE_LIMIT |
Bandwidth limit for downloads (e.g., 5M for 5 MiB/s, default 0 = unlimited). Supports suffixes K, M, G (case-insensitive). |
CD_DOWNLOAD_MAX_RETRIES |
Maximum retry attempts per connection failure (default 3, clamped between 0 and 20). |
CD_FORCE_NO_COLORS |
When set, disables ANSI colours in Chroot-Distro output. |
CHROOT_DISTRO_NO_ELEVATE |
When set to 1, disables privilege auto-elevation (same as --no-elevate). |
CHROOT_DISTRO_USE_SUDO |
When set to 1, prefer sudo over su on Termux (same as --use-sudo). |
COLUMNS |
Fallback terminal width for --help rendering. |
TERM, COLORTERM |
Inherited into the guest (always; even in --minimal). TERM defaults to xterm-256color when unset on the host. |
These are set automatically by chroot-distro at login. They cannot be
overridden from manifest.json image Env, but can be overridden with
--env.
Display and audio (Linux, non-minimal, display sharing active):
| Variable | Source / Fallback |
|---|---|
DISPLAY |
Host $DISPLAY; fallback :0 |
XAUTHORITY |
Host $XAUTHORITY; fallback ~/.Xauthority; fallback Xwayland auth file in /run/user/<uid>/ |
XDG_RUNTIME_DIR |
Host $XDG_RUNTIME_DIR; fallback /run/user/<uid> |
WAYLAND_DISPLAY |
Host $WAYLAND_DISPLAY; fallback wayland-0 if socket exists |
XDG_SESSION_TYPE |
Host $XDG_SESSION_TYPE (no fallback) |
XDG_CURRENT_DESKTOP |
Host $XDG_CURRENT_DESKTOP (no fallback) |
DESKTOP_SESSION |
Host $DESKTOP_SESSION (no fallback) |
PULSE_SERVER |
Host $PULSE_SERVER; fallback unix:/run/user/<uid>/pulse/native if socket exists |
DBUS_SESSION_BUS_ADDRESS |
Host $DBUS_SESSION_BUS_ADDRESS; fallback unix:path=/run/user/<uid>/bus if socket exists |
GPU — NVIDIA native Linux (auto-detected, non-minimal):
| Variable | Value |
|---|---|
__NV_PRIME_RENDER_OFFLOAD |
1 |
__GLX_VENDOR_LIBRARY_NAME |
nvidia |
GPU — WSL2 with NVIDIA (auto-detected, non-minimal):
| Variable | Value |
|---|---|
GALLIUM_DRIVER |
d3d12 |
MESA_D3D12_DEFAULT_DEVICE_TYPE |
GPU |
LIBGL_ALWAYS_SOFTWARE |
0 |
Completion scripts for Bash, Zsh, and Fish live in
src/chroot_distro/completions/:
chroot-distro.bash_chroot-distrochroot-distro.fish
They complete subcommands, global flags (--no-elevate, --use-sudo),
and per-command options (including login/run flags such as
--shared-home, --shared-display, --get-chroot-cmd, --isolated,
and --minimal).
If your shell does not pick them up automatically, install them manually:
# Bash
mkdir -p ~/.local/share/bash-completion/completions
cp src/chroot_distro/completions/chroot-distro.bash \
~/.local/share/bash-completion/completions/chroot-distro
# Zsh (add fpath before compinit in ~/.zshrc)
mkdir -p ~/.zsh/completions
cp src/chroot_distro/completions/_chroot-distro ~/.zsh/completions/_chroot-distro
# Fish
mkdir -p ~/.config/fish/completions
cp src/chroot_distro/completions/chroot-distro.fish \
~/.config/fish/completions/chroot-distro.fish- Root required: real
chrootand bind mounts need appropriate privileges; there is no rootless mode. - No real init:
systemd, socket-activated supervisors, and full init systems generally do not work. Individual long-running processes are fine. - Kernel features: FUSE modules, real
iptables, custom cgroup hierarchies, and similar kernel-module features may not work inside the guest. - Namespaces:
--isolatedprovides mount/PID/UTS/IPC isolation viaunshare/nsenter, but there is no network namespace and no parity with Docker or Podman. - Bind mount hygiene: crashed sessions or orphan processes can leave
mounts busy;
unmountand lazy unmount mitigate this but orphaned processes should be cleaned up.
- Termux requires root: unlike proot-distro, Chroot-Distro cannot run containers on a non-rooted Android device.
- Registry authentication: private pulls and pushes need
CD_DOCKER_AUTH=user:password(orPD_DOCKER_AUTH). Dockerconfig.jsoncredential helpers are not read. - Dockerfile builds are not BuildKit:
RUNexecutes underchroot, not a real container runtime. BuildKit-only Dockerfile features are rejected. Multi-platform manifest lists are not produced — build and push once per architecture. pushis single-arch: no manifest-list assembly, cross-repo blob mounting, or chunked uploads.- No live state migration:
backup/restorecapture the rootfs and manifest, not in-memory process state.
If this project is useful to you, tips in cryptocurrency are welcome:
Bitcoin
13Q7xf3qZ9xH81rS2gev8N4vD92L9wYiKH
Ethereum / USDT (BEP20, ERC20)
0x1d216cf986d95491a479ffe5415dff18dded7e71
USDT (TRC20)
TCjRKPLG4BgNdHibt2yeAwgaBZVB4JoPaD
Dogecoin
DJkMCnBAFG14TV3BqZKmbbjD8Pi1zKLLG6
- Bug reports: https://github.com/sabamdarif/chroot-distro/issues
- License: GPL-3.0-only. See LICENSE.
- proot-distro — architecture and CLI design inspiration.
- pyLoad — sliding-window speed tracking, token-bucket rate limiting, and connection resilience algorithms.
- distrobox - shared-display option improvements
- Magisk-Modules-Alt-Repo/chroot-distro
- ravindu644/Ubuntu-Chroot