PRoot-Distro: Rootless OCI Containers in Termux and on Linux

What PRoot-Distro solves, and who should care

On Android there is no root, no Docker daemon and no kernel module to load, so the usual container tooling does not apply. PRoot-Distro fills that gap by using proot to give a chroot-like environment without root access. The README describes it as a utility for managing rootless Linux containers in Termux and on regular Linux hosts, and it names four typical uses: a desktop-class distribution on a phone or tablet, cross-compiling for another CPU architecture through QEMU user-mode, running server software such as Nginx, Nextcloud or PostgreSQL on Android from the same OCI images you would use on a server, and building custom OCI images from a Dockerfile on-device. The audience is therefore people who already live in Termux, plus Linux users who want a throwaway distro without touching the host. The CLI ships as both proot-distro and the shorter alias pd, so the same commands work in either form.

How the container filesystem is assembled from OCI layers

The mechanism is image-based rather than template-based. Containers are created by pulling Docker/OCI images directly from Docker Hub or any compatible registry, or by extracting a local tarball or OCI image archive. The container filesystem is assembled from the image layers and stored locally, ready to be entered at any time. That means the registry reference you type is a standard Docker image reference: ubuntu:24.04, a bare alpine that resolves to latest, a user image like myuser/myimage:tag, or a custom registry such as ghcr.io/foo/bar. The install command also takes -a / --architecture, which accepts native names (aarch64, arm, i686, riscv64, x86_64) or Docker platform strings (linux/arm64, linux/amd64, linux/arm/v7, linux/386, linux/riscv64), defaulting to the host CPU. Cross-architecture containers are where the optional qemu-user-* package comes in. On startup the tool verifies that proot is available; on Termux with an interactive terminal it offers to install it, otherwise it prints an install hint and exits. It also refuses to run inside another proot, since nested proot is not supported by proot itself, and warns if launched as root. The build side is separate but related: PRoot-Distro can build OCI images from a Dockerfile with no Docker daemon, storing the result in the local manifest cache or exporting it as a standalone OCI tarball.

Installing PRoot-Distro and entering your first container

On Termux the primary distribution channel is pkg, which pulls in proot automatically. Install Termux from F-Droid or the Termux GitHub Releases first, then run:

pkg install proot-distro

If you would rather take the latest published version from PyPI, the README gives this alternative, which installs python and proot through pkg and then the package through pip:

pkg install python proot
pip install proot-distro

On a regular Linux host you install proot through your distribution's package manager, for example on Debian or Ubuntu, then pip install proot-distro from PyPI, or clone the repository and run pip install . from the checkout. Python 3.9 or newer is required, and the only runtime dependency is proot.

Once installed, the quick-start sequence is short. Search Docker Hub, install Ubuntu 24.04, then start a shell:

proot-distro search ubuntu
proot-distro install ubuntu:24.04
proot-distro login ubuntu

The login command drops you into a shell inside the container. You can also run a single command and exit, which is the form to use in scripts:

proot-distro login ubuntu -- /bin/uname -a

After that, proot-distro list shows installed containers, and proot-distro list --image shows the OCI images sitting in the local cache. The alias pd works everywhere proot-distro does, so pd sh ubuntu is the same as proot-distro login ubuntu.

Lifecycle commands beyond install and login

The command set is broader than the quick start suggests, and it is where the tool earns the word managing. install has aliases add, i, in and ins, and takes -n / --name to set a custom local name; the name must start with a letter or digit and may contain only letters, digits, underscore, dot and hyphen, and an empty name is rejected. The deprecated long form --override-alias is still accepted, which tells you the naming behaviour changed at some point. There is a --quiet flag to suppress non-error output. Around the container itself you get remove, rename, reset (reinstall from scratch, losing all in-container data), backup and restore for archiving, copy and sync for moving files in and out, and clear-cache to delete the download cache. Session handling is separate: ps lists active sessions and kill stops them. On the image side, build takes a Dockerfile context and can install the result directly with --install-as, and push publishes a built image to a registry using credentials from PD_DOCKER_AUTH. The README's own example exports PD_DOCKER_AUTH as a user:password pair before pushing myuser/myapp:1.0. Every command supports --help, -h and --usage, with help text laid out for the current terminal width, and shell completions for bash, zsh and fish are shipped as package data.

Where proot gets in the way

The fundamental limitation is proot itself. It provides a chroot-like environment through syscall interception rather than kernel namespaces, so anything that depends on real namespace isolation, on mounting filesystems, or on a full init system is a poor fit. The README has a dedicated Limitations section, and the honest reading is that PRoot-Distro inherits proot's constraints rather than working around them. Two behaviours are documented explicitly and are worth planning around: nested proot is not supported, so you cannot run PRoot-Distro inside another proot session, and running as the root user produces a warning. Cross-architecture containers need a qemu-user-* package installed separately, which adds its own overhead on top of proot's. If your workload is a database under sustained load, a build that spawns thousands of processes, or anything that expects systemd, this is the wrong tool and a real VM or a privileged container runtime is the right one. The trade-off is deliberate: you give up isolation and some performance to gain the ability to run a Linux userland where no other option exists.

PRoot-Distro compared with Andronix and plain chroot

The search results around this project pair it with Andronix and with chroot, and the difference is architectural. Andronix is a distribution channel: it gives you scripts and prebuilt rootfs tarballs to set up a Linux environment on Android, and historically those setups leaned on the same proot mechanism underneath. PRoot-Distro is the runtime and the manager, and it takes the image from the registry rather than from a curated tarball, which is why the same ubuntu:24.04 you run on a server is what you install on the phone. A chroot is a different animal entirely: it requires root or CAP_SYS_CHROOT, it changes the root directory for the process, and it does not intercept syscalls. On Android that is normally unavailable, which is exactly why proot exists. If you have root and want a real chroot, proot-distro is not the tool. If you want a maintained CLI with install, list, backup, restore, build and push in one place, and you are willing to accept proot's semantics, it is a reasonable default.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-09-23. Recent releases are close together: v5.7.0 on 2026-08-19, v5.8.0 on 2026-08-22 and v5.9.0 on 2026-09-19, which suggests a steady release cadence rather than a frozen project. pyproject.toml declares version 5.9.0, requires Python 3.9 or newer, and lists no mandatory runtime dependencies beyond the Python standard library; the test extra is pytest>=7, and there is a live marker for tests that hit the network or execute proot, skipped unless RUN_LIVE_TESTS=1 is set. Upgrading through pkg or pip is the normal path, but note that reset is destructive by design: it reinstalls a container from scratch and loses all in-container data, so backups matter more than version numbers. The licence is GPL-3.0-only, declared both in the repository and in pyproject.toml. That is a copyleft licence, so if you redistribute a modified version or bundle it into a larger work, the obligations travel with it; consult your own counsel about your specific distribution model rather than treating this as legal advice.

Editorial conclusion

Adopt PRoot-Distro if you want a full Linux userland on an Android device or an unprivileged Linux host and can accept proot's syscall and ptrace overhead, or if you want to build OCI images on-device without a Docker daemon. Skip it if you need kernel namespaces, systemd, Docker-in-Docker or near-native performance; proot cannot provide those. Before committing, verify that your target image actually boots under proot, check the architecture you need is covered by a qemu-user package, and read the Limitations section in the README for your specific workload.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. termux/proot-distro on GitHub