PRoot-Distro

PRoot-Distro is a utility for managing rootless Linux containers in Termux and on regular Linux hosts. It uses proot to provide a chroot-like environment without requiring root access on the device.

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.

PRoot-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.

Donate

If you enjoy using PRoot-Distro, I will be grateful for your support! This is very important to keep the project up in long term, deliver new features and bugfixes.

Donate via Patreon: https://patreon.com/SylirreOSS

Or send a tip in Bitcoin:

bc1qxuwtc0sfjt43n3sufck6s0gaeand8eaeguajxs

---

Table of contents

1. Introduction
2. Installation
3. Quick start
4. Commands
   • install
   • search
   • build
   • push
   • login
   • run
   • list
   • ps
   • kill
   • remove
   • rename
   • reset
   • backup
   • restore
   • copy
   • sync
   • clear-cache
5. How PRoot-Distro works
6. Storage layout
7. Environment variables
8. Shell completions
9. Limitations
10. Donate

---

Introduction

PRoot-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 an Android device, or on top of a regular Linux distribution, without root, without a kernel module, and without a Docker daemon.

Typical use cases:

• Running a desktop-class Linux distribution on a phone or tablet.
• Cross-compiling for a different CPU architecture using QEMU user-mode.
• 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 needing a Docker daemon — and pushing them straight to Docker Hub, GitHub Container Registry, or any other OCI-compatible registry.
• Trying a distribution non-destructively: install, mess around, proot-distro remove when done.

The CLI is exposed both as proot-distro and the shorter alias pd.

Installation

PRoot-Distro is primarily distributed via Termux's pkg package manager and via PyPI. Python 3.9 or newer is required. The only runtime dependency is proot (and, optionally, a qemu-user-* package for cross-architecture containers).

On Termux (Android)

Install Termux from F-Droid or the Termux GitHub Releases. Then, inside Termux:

pkg install proot-distro

This pulls in proot automatically as a dependency.

To install the latest published version from PyPI instead:

pkg install python proot
pip install proot-distro

On a regular Linux host

# Install proot via your distro's package manager, e.g. on Debian/Ubuntu:
sudo apt install proot python3-pip

pip install proot-distro          # from PyPI
# or
git clone https://github.com/termux/proot-distro
cd proot-distro
pip install .                     # from a local checkout
pip install -e .                  # editable install for development

First-run check

On startup the tool verifies that proot is available. If it isn't:

• On Termux, with an interactive terminal, you are prompted to install it via pkg install -y -q proot.
• Otherwise, an install hint is printed and the program exits.

Set PD_PROOT_BIN to use a custom proot executable instead of the PATH lookup; see the environment variables table below.

PRoot-Distro also refuses to run inside another proot (nested proot is not supported by proot itself) and prints a warning if launched as the root user.

Quick start

# Look up images on Docker Hub
proot-distro search ubuntu

# Install Ubuntu 24.04 from Docker Hub
proot-distro install ubuntu:24.04

# Start a shell inside the container
proot-distro login ubuntu

# Same thing, but using the short command alias
pd sh ubuntu

# Run a single command and exit
proot-distro login ubuntu -- /bin/uname -a

# List all installed containers
proot-distro list

# List the OCI images sitting in the local cache
proot-distro list --image

# Build and install a custom image from a Dockerfile
proot-distro build -t myapp:1.0 --install-as myapp ./mycontext

# Publish the built image to a registry
export PD_DOCKER_AUTH=myuser:mypassword
proot-distro push myuser/myapp:1.0

# Rebuild from scratch (loses all in-container data)
proot-distro reset ubuntu

# Permanently remove a container
proot-distro remove ubuntu

---

Commands reference

The pd short alias works everywhere proot-distro does.

This is the beginning of the README. Read the rest at the original. Read the full README ↗