< Back to all hacks

#01 proot-distro Manual Install

Infrastructure
Problem
proot-distro not available in Termux repos for Android 5/6 (ARM32, old API level).
Solution
Download from GitHub releases, manually fix TERMUX_PREFIX placeholders, install with dpkg.
Lesson
Termux repos drop old Android versions. Manual install works if you patch paths.

Context

The Moto E2 runs Android 6.0 (API 23) on a Snapdragon 410 (Cortex-A53 in 32-bit mode). Termux's apt-android-5 repository variant is the only one that supports this old API level, and it has a significantly reduced package selection. proot-distro is not included because the maintainers consider proot on Android 5/6 unsupported.

Without proot-distro, there is no easy way to bootstrap a Linux root filesystem inside Termux. The alternative would be manually downloading and extracting a rootfs tarball, then invoking proot with all the right flags by hand. proot-distro automates all of that, so getting it installed is worth the effort.

This hack is marked LEGACY. The entire proot layer was removed during the native migration on Feb 15, 2026. The gateway now runs directly on Termux with a native Node.js binary and an LD_PRELOAD compat shim. This documentation is preserved for reference.

Implementation

Install proot and its dependencies first, since these are available in the apt-android-5 repo:

pkg install proot tar wget curl

Find the latest proot-distro release on GitHub and download the .deb for all architectures:

cd ~
curl -sLO https://github.com/termux/proot-distro/releases/download/v4.7.0/proot-distro_4.7.0_all.deb

Attempt a direct install first to see what happens:

dpkg -i proot-distro_4.7.0_all.deb

This fails or produces a broken install because the .deb contains scripts with @TERMUX_PREFIX@ and @TERMUX_HOME@ placeholders that dpkg does not resolve. The fix is to extract, patch, and repack:

mkdir -p /tmp/proot-fix
dpkg-deb -R proot-distro_4.7.0_all.deb /tmp/proot-fix

# Replace all placeholder occurrences with actual Termux prefix
find /tmp/proot-fix -type f -exec sed -i \
  "s|@TERMUX_PREFIX@|/data/data/com.termux/files/usr|g" {} +

# Also patch TERMUX_HOME if present
find /tmp/proot-fix -type f -exec sed -i \
  "s|@TERMUX_HOME@|/data/data/com.termux/files/home|g" {} +

# Repack and install
dpkg-deb -b /tmp/proot-fix proot-distro-fixed.deb
dpkg -i proot-distro-fixed.deb

# Clean up
rm -rf /tmp/proot-fix proot-distro_4.7.0_all.deb proot-distro-fixed.deb

After installation, verify proot-distro can list available distributions:

proot-distro list

Then install Ubuntu (the rootfs used for OpenClaw before the native migration):

proot-distro install ubuntu

The rootfs lands at $PREFIX/var/lib/proot-distro/installed-rootfs/ubuntu, taking roughly 300-400 MB of disk space.

Verification

  • which proot-distro returns $PREFIX/bin/proot-distro.
  • proot-distro list shows available distros without errors about unresolved placeholders.
  • proot-distro login ubuntu drops into a root shell inside the Ubuntu rootfs.
  • cat /etc/os-release inside proot shows the expected Ubuntu version.
  • grep -r 'TERMUX_PREFIX' $PREFIX/bin/proot-distro returns no matches (all placeholders resolved).

Gotchas

  • The .deb version must match the proot binary version already installed in Termux. A mismatch causes "unsupported distro plugin version" errors at runtime.
  • @TERMUX_PREFIX@ appears in both shell scripts and config files inside the .deb. Missing even one occurrence causes silent failures where proot-distro tries to access /usr/ instead of $PREFIX/.
  • dpkg on Termux does not run postinst scripts from the .deb reliably. If proot-distro creates symlinks or directories in its postinst, those must be created manually after patching.
  • On Android 6, the proot --link2symlink flag is essential because the underlying filesystem does not reliably support hard links from userspace. This is handled by the run-proot.sh helper (hack 7), not by proot-distro itself.
  • The downloaded rootfs consumes 300-400 MB. On a phone with roughly 4 GB internal storage, disk space is a real constraint. Monitor with df -h $PREFIX before and after installation.
  • If dpkg fails with dependency errors before you even get to the placeholder issue, install the listed dependencies with pkg install first. Common missing deps are bash, coreutils, and findutils.

Result

proot-distro runs on the Moto E2 despite not being in the official apt-android-5 repos. Ubuntu 25.10 ARM rootfs installs and boots inside proot, providing a full Linux environment with apt, bash, and standard GNU tools. This was the foundation for running Node.js 22 and OpenClaw before the native migration eliminated the proot layer entirely, freeing roughly 10-15 MB of RSS overhead and significantly reducing syscall latency.