Self-hosted service
termux/proot-distro avatar
termux/proot-distro

proot-distro: seventeen commands, no Python dependencies, and one root check that only warns

A utility for managing proot containers.

3,645 stars504 forksPythonGPL-3.0

At a glance

What is it?
A Python utility that assembles Linux userlands from OCI images on Termux or a regular Linux host, using proot instead of a kernel mechanism, so no root, no kernel module and no Docker daemon are needed. It declares zero Python dependencies, offers to install its own dependency for you on first run, refuses to run inside another proot, and only warns when launched as root.
Who is it for?
proot-distro fits someone on an Android device who wants a real Debian or Ubuntu userland without rooting the phone, or someone on a Linux host who wants to pull an OCI image and poke at it destructively without a container daemon. Three things to know before you rely on it.
Can I use it commercially?
Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • termux/proot-distro3,645 ★ · +142
Star history
Repository2026-09-242026-11-15
termux/proot-distro3.5k3.6k

142 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Seventeen commands, two entry points, and no dependencies

The command reference is longer than most projects of this size manage, and the table of contents enumerates seventeen of them: install, search, build, push, login, run, list, ps, kill, remove, rename, reset, backup, restore, copy, sync and clear-cache. Beyond the expected lifecycle commands there are three that are less common in this kind of tool, a reset that reinstalls a container from scratch, a backup and restore pair that archive one, and a copy command that moves files in or out. The short alias works everywhere the long name does, and the packaging confirms it is not a wrapper: both console entry points resolve to the same function in the command module. The manifest declares no runtime dependencies at all, with the only extra being a test group. That is consistent with the README's statement that the only runtime dependency is the proot binary itself, optionally a QEMU user-mode package for cross-architecture work.

On first run it offers to install proot for you

There is a startup check for the proot binary, and on Termux the response is not an error but a prompt. With an interactive terminal the tool asks to install it through the Termux package manager, running an install command with the assumptions and quiet flags already supplied. Off Termux, or without a terminal to prompt at, it prints a hint and exits. So the first launch of a fresh install can install a package on your behalf, which is the sort of convenience that is welcome on a phone and worth thinking about on a shared machine. Two environment variables sit alongside it. One overrides which proot executable is used instead of looking it up on the path, which means the program you run is whatever that variable points at. The other supplies registry credentials, so a private image password ends up living in an environment variable rather than a credential store.

Nested proot is refused, running as root only warns

Two safety checks are described in the same sentence and they are not equally strong. Nested proot is refused outright, and the stated reason is that proot itself does not support it, so the tool is not choosing a policy there, it is passing on a limitation. Running as the root user, by contrast, prints a warning and continues. That asymmetry is the one to sit with, because root is precisely the case the project's headline claim is about: it advertises running without root, and the check that would matter most for that claim is the softer of the two. The rest of the design points the same way. It states up front that no root is required, no kernel module is required and no Docker daemon is required, and the isolation comes from a userspace program intercepting system calls rather than from kernel-enforced boundaries.

Registry access uses the standard challenge, with anonymous tokens for public images

Image references follow Docker's own conventions, and the tool decides how to authenticate by looking at the reference. An official image with a tag, an official image without one which defaults to the latest tag, a user image, and a custom registry host are all accepted, and a registry is recognised when the first path component contains a dot or a colon, which is the standard way of spotting a hostname. For public images on the common hosts, the README says the pull uses an anonymous bearer token discovered from each registry's version-two challenge endpoint, which is the registry protocol doing its own thing rather than a credential being bundled. Private images need credentials supplied separately. Combined with the architecture option, which accepts both bare CPU names and full Docker platform strings and defaults to whatever the host is, the install path is mostly a thin, well-informed client.

Five architectures, two spellings each, and a deprecated flag still accepted

The architecture override is the most carefully specified option in the reference. It takes native names covering five architectures, or Docker platform strings for the same five, and defaults to the host CPU, with cross-architecture containers relying on a QEMU user-mode package from the host. The naming option is specified just as tightly: the rules state that a custom name must begin with a letter or a digit, may contain only letters, digits, `underscore`, dot and hyphen, and that an empty name is rejected. It also records its own history. The current short and long form is documented, and a longer deprecated form is still accepted for compatibility, which is worth knowing if you have scripts written against the old spelling. Help text is not an afterthought either, since every command supports it under three different spellings and the output is laid out for the terminal it is printed to.

It builds images from a Dockerfile without a daemon, and can push them

The second half of the tool is an image builder, which is the part that distinguishes it from a downloader. It can build an OCI image from a Dockerfile on the device with no Docker daemon involved, storing the result in the local manifest cache or exporting it as a standalone OCI tarball:

sh
proot-distro build -t myapp:1.0 --install-as myapp ./mycontext

That single command tags the result and installs it as a container in one step. From there the push command publishes a built image to a registry, and the use cases name Docker Hub and GitHub Container Registry among the destinations. The intro frames the whole thing as a try-it-and-throw-it-away workflow: install a distribution non-destructively, mess around with it, remove it when you are done. The command list backs that up with remove and clear-cache sitting alongside the rest.

The test suite separates anything that touches the network or runs proot

The test configuration is one of the more telling parts of the manifest. The project defines a custom marker called live, described as tests that hit the network or execute proot, and states that they are skipped unless a specific environment variable is set. So by default the suite neither reaches out to a registry nor launches the container runtime, which means the default test run is hermetic and the integration surface is opt-in by deliberate choice rather than by accident. The test path is set to the tests directory at the root, the only test dependency is pytest with a floor of seven, and the repository also carries an agent instruction file and a security policy alongside the readme and the licence.

Completions for three shells, and a GPL tool on PyPI

Shell completion is wired up properly, with three separate completion files: one for bash installed into the bash-completion completions directory, one for zsh into its site-functions directory, and one for fish into its vendor completions directory. The completions are also declared as package data, so they travel inside the installed package rather than only being copied into system paths. Two other packaging details are worth a reader's attention. The project is licensed GPL-3.0-only, and it is distributed through PyPI and pip as well as through the Termux package manager, so a copyleft tool is being installed by a package index that most people associate with permissive libraries. And the project declares its Python floor as 3.9 or newer, with the build backend pinned to a recent setuptools, while the newest release is 5.9.0 and the manifest agrees.

Editorial conclusion

proot-distro fits someone on an Android device who wants a real Debian or Ubuntu userland without rooting the phone, or someone on a Linux host who wants to pull an OCI image and poke at it destructively without a container daemon. Three things to know before you rely on it. The isolation is a userspace interception rather than a kernel boundary, so treat a container as untrusted-by-default and keep anything sensitive on the host outside it. The tool will offer to install its own dependency through the Termux package manager on first run, which is convenient and is a decision your terminal made for you. And the guard rails are asymmetric: running inside another proot is refused outright, while running as root only prints a warning, so do not rely on the tool to stop you there. The documentation is unusually complete for a project this size, with seventeen commands and a limitations section.

Frequently asked questions

What is Proot-distro in Termux?

A utility for managing rootless Linux containers in Termux and on regular Linux hosts. It uses proot to give a chroot-like environment without root access, assembling a container filesystem from the layers of a Docker or OCI image pulled from a registry, and it can also build OCI images from a Dockerfile without a Docker daemon.

How to install Proot-distro?

On Termux, install Termux itself and then run `pkg install proot-distro`, which pulls in proot as a dependency; Python 3.9 or newer is required. On a Linux host, install proot through the distribution's package manager and then `pip install proot-distro`, or clone the repository and run `pip install .` or `pip install -e .` from a local checkout.

Is Proot-distro safe to use?

The repository states that it needs no root, no kernel module and no Docker daemon, and that it refuses to run inside another proot. Launching as root produces a warning rather than a refusal. Isolation comes from proot intercepting calls in userspace rather than from a kernel boundary, so a container is not a security boundary against the host.

What does proot stand for?

The repository does not expand the name anywhere. It links to the proot project as the mechanism it uses, calls itself a chroot-like environment built on it, and describes the container as rootless because of it, but it gives no derivation of the word.

How do I pull a private container image with proot-distro?

Supply credentials through the environment variable the README names for that purpose. Public images need none: on the common public registries the pull uses an anonymous bearer token discovered from the registry's version-two challenge, and a custom registry is recognised when the first path component of the reference looks like a hostname.

Official sources

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

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/termux-proot-distro.svg)](https://hysenlabs.com/projects/termux-proot-distro)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/termux-proot-distro.svg)](https://hysenlabs.com/projects/termux-proot-distro)

Was this useful?