Version 5.0 release notes

[sylirre]

Version 5.0 maintains compatibility with older versions where possible, but brings some fundamental changes which may not be favored by some users.

Key differences:

• Rewritten in Python

  Older versions of proot-distro already was an overgrown Bash script with well-known bottleneck of execution speed and strong dependency on external utilities (e.g. curl), also specifics of shell scripting make it very hard to add any complex functionality.

  Rewriting it to Python makes it way better, but now this means proot-distro needs a python package to be installed.

• OCI image registry as primary source for distribution downloads

  Docker Hub and other public registries provide Linux distribution base images as well as already prepackaged application sets. This is also a convenient way for a lot of people and organizations outside the Termux community to build and share their stuff. So why not?

  PRoot-Distro still keeps support for installation from plain rootfs archives.

• PRoot-Distro no longer provides own rootfs tarballs

  Particularly not in the official way, as I may still provide rootfs tarballs and build recipes occasionally.

  But in general I expect that community will contribute to Termux/Linux ecosystem, to build and keep up the stuff they are interested in rather than relying on me.

Distribution images provided on Docker Hub may show a bit different behavior than what was previously provided by proot-distro v4.x:

• Minimized: for example no man utility and no manual pages. Sometimes you'll need to run unminimize command (e.g. in debian), on some others you'll need to edit package manager config (e.g. rpm-based distributions) and reinstall wanted packages to get docs.
• Set of default packages can be different: a case with recent Ubuntu releases (25.10+) where GNU coreutils replaced with Rust-based variant and caused coreutils: unknown program 'loader' error until proot fix was made.
• No out-of-box distribution-specific fixes: registry provides "vanilla" kind of images and making fixes for everything through proot-distro package is not feasible.

---

Now answering some questions before they will start to pop up in issue tracker.

1. What distributions supported by proot-distro v5?

In general all existing Linux distributions are supported, providing their environment can run under proot.

2. Where can I find distributions?

On Docker Hub by using search. Good starting point: https://hub.docker.com/search?type=image&categories=Operating+systems&architecture=arm64&operating_system=linux

3. I used proot-distro v4 before, what will happen after upgrade?

When you will run proot-distro login <old-container>, the utility will apply all necessary changes for further seamless usage. However that change can't be easily reverted - consider this while upgrading.

4. None of base tools work in Ubuntu now, what to do?

If you see coreutils: unknown program 'loader', then upgrade proot package.

PRoot-Distro requires proot 5.1.107-71 or newer. You cannot use proot pulled elsewhere from third parties or original variant in Termux.

5. Desktop doesn't work, why?

Ubuntu 24.04 and Debian 12 should work. Newer versions indeed may not and this is independent of proot-distro.

Newest distribution versions ship gdk-pixbuf package that depends on /usr/bin/bwrap and this utility requires Linux namespaces to work. The workaround is tricky: termux/termux-packages#28421 (comment)

---

Utility provides a nice built-in help information for getting started (proot-distro help), but just in case leaving essentials there. I'll take Ubuntu 24.04 for examples.

Install distribution:

proot-distro install ubuntu:24.04

Use option --name to set custom name for container. Omitting :24.04 will cause installation of the latest published version (26.04 by date of this post).

Start shell:

proot-distro login ubuntu

Remove container:

proot-distro remove ubuntu

Recommended distributions to try:

• alpine:3.23
• archlinux/archlinux:base-20260517.0.530531 (x86_64!)
• danhunsaker/archlinuxarm:20260517
• chimeralinux/chimera:latest
• debian:12
• fedora:44
• gentoo/stage3:20260511 (disable sandbox via /etc/portage/make.conf)
• manjarolinux/base:20260322
• nixos/nix:2.32.8
• opensuse/leap:15
• rockylinux/rockylinux:10
• aclemons/slackware:current
• termux/termux-docker:aarch64
• ubuntu:24.04

---

If you have any objections about Python rewrite, project direction, maintainer's decision and AI usage for development, I would recommend to look for alternatives rather than sending complaints.

[robertkirkman]

• termux/termux-docker:aarch64

I have noticed that, like you show, when using termux-docker on proot-distro on aarch64, it is necessary to explicitly specify :aarch64 otherwise it will download a x86_64 image.

I was wondering: Docker on aarch64 Ubuntu laptop PC is not affected by this problem

is proot-distro now similar enough to Docker that it could be possible for it to have the same kind of ability to run termux-docker without explicitly specifying :aarch64 that Docker on aarch64 Ubuntu laptop PC has, or is that hard to implement?

[sylirre]

Termux-docker needs to stop using tags like aarch64. That should be enough.

Just push images for different platforms under same generic tag (e.g. timestamp).

[robertkirkman]

I was wondering: Docker on aarch64 Ubuntu laptop PC is not affected by this problem

actually, I might be wrong about this, I thought that it was not affected since I remembered it being unaffected but I might have remembered wrong. I will check that again, sorry

EDIT: yes it is also affected and I was wrong.

[arfshl]

Recommended distributions to try:

* `alpine:3.23`

* `archlinux/archlinux:base-20260517.0.530531` (x86_64!)

* `danhunsaker/archlinuxarm:20260517`

* `chimeralinux/chimera:latest`

* `debian:12`

* `fedora:44`

* `gentoo/stage3:20260511` (disable sandbox via /etc/portage/make.conf)

* `manjarolinux/base:20260322`

* `nixos/nix:2.32.8`

* `opensuse/leap:15`

* `rockylinux/rockylinux:10`

* `aclemons/slackware:current`

* `termux/termux-docker:aarch64`

* `ubuntu:24.04`

i think this is should be on README

and how about override tarball env? any pd v5 equivalent for this?

[robertkirkman]

yes, termux-docker is also affected by that on Ubuntu aarch64 laptops and I was wrong, I'm sorry.

Termux-docker needs to stop using tags like aarch64. That should be enough.

Just push images for different platforms under same generic tag (e.g. timestamp).

I never understood the purpose of the tag format of termux-docker, and I was afraid to mess it up if it was how it is on purpose, for example in particular there is some code in certain places that relies on the $TERMUX_ARCH variable matching the tag name of the termux-docker architecture. I only changed the latest tag from i686 to x86_64 because 2 Termux contributors asked me to do that so I thought it would be best to make that change and keep everything else the same.

However, I never understood the purpose of why the tag format of termux-docker includes the latest tag. Do you know what the purpose of the latest tag is? If only the latest tag were removed is there a chance that could fix this?

[dioput12]

So far, my alpine:edge installation for qutebrowser has been running smoothly, and my pulseaudio configuration is still working fine.

[sylirre]

and how about override tarball env? any pd v5 equivalent for this?

PD_OVERRIDE_TARBALL_URL no longer used here.

Pass the file name to proot-distro install when need to use tar archive installation method.

curl -LO https://github.com/termux/proot-distro/releases/download/v4.34.2/archlinux-aarch64-pd-v4.34.2.tar.xz
proot-distro install --name archlinux ./archlinux-aarch64-pd-v4.34.2.tar.xz

[arfshl]

and how about override tarball env? any pd v5 equivalent for this?

PD_OVERRIDE_TARBALL_URL no longer used here.

Pass the file name to proot-distro install when need to use tar archive installation method.

curl -LO https://github.com/termux/proot-distro/releases/download/v4.34.2/archlinux-aarch64-pd-v4.34.2.tar.xz
proot-distro install --name archlinux ./archlinux-aarch64-pd-v4.34.2.tar.xz

How about void linux? I can't find void on dockerhub

[sylirre]

Docker Hub is just default registry. You can use any other source available, whether it is OCI image or simple rootfs archive.

Void Linux publishes official images on GitHub Container registry at https://github.com/orgs/void-linux/packages

proot-distro install --name voidlinux ghcr.io/void-linux/void-musl:20260501r1
proot-distro run voidlinux

Their images don't have /bin/bash for some reason but it is specified as login shell for root which cause error. Use proot-distro run instead of login to execute image-defined command.

[arfshl]

Distribution	Registry
Almalinux	almalinux
Alpine Linux	alpine:latest
Alpine Linux Edge	alpine:edge
Arch Linux x64	archlinux/archlinux
Arch Linux ARM	arfshl/archlinuxarm:latest
Artix Linux	artixlinux/artixlinux
Chimera Linux	chimeralinux/chimera:latest
Debian Stable	debian:stable
Debian Sid	debian:sid
Debian Testing	debian:testing
Fedora	fedora
Fedora Rawhide	fedora:rawhide
Gentoo (disable sandbox via /etc/portage/make.conf)	gentoo/stage3
Manjaro	manjarolinux/base
openSUSE Leap	opensuse/leap
openSUSE Tumbleweed	opensuse/tumbeweed
Oracle Linux	oraclelinux:10
Rocky Linux	rockylinux/rockylinux:10
Slackware	aclemons/slackware:current
Termux	termux/termux-docker:aarch64
Trisquel arm	arfshl/trisquel:latest
Ubuntu Latest	ubuntu:latest
Ubuntu LTS	ubuntu:rolling
Void glibc	ghcr.io/void-linux/void-glibc:latest
Void musl	ghcr.io/void-linux/void-musl:latest

[dioput12]

I think it’s best to let users know as well, since the installation location has changed from $PREFIX/var/lib/proot-distro/installed-rootfs to$PREFIX/var/lib/proot-distro/containers. $PREFIX/var/lib/proot-distro/dlcache is still same location after upgrade.

[sylirre]

If user has any existing v4 container, it will be automatically modified for v5 during proot-distro login. User should not attempt to manually move container because this will break any existing link2symlink structures.

Rootfs stored at location

$PREFIX/var/lib/proot-distro/containers/<insert-name-here>/rootfs

$PREFIX/var/lib/proot-distro/dlcache is subject for renaming in v5.1 because it will contain build cache as well, besides downloads.

[dioput12]

If user has any existing v4 container, it will be automatically modified for v5 during proot-distro login. User should not attempt to manually move container because this will break any existing link2symlink structures.

Rootfs stored at location

$PREFIX/var/lib/proot-distro/containers/<insert-name-here>/rootfs

$PREFIX/var/lib/proot-distro/dlcache is subject for renaming in v5.1 because it will contain build cache as well, besides downloads.

My bad, sorry. Thanks for your clarification.