### Set Up Development Environment

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/README.md

Example command to install a Ubuntu container and name it 'dev' for setting up a development environment.

```bash
# Install Ubuntu container
proot-distro install ubuntu:24.04 --name dev
```

--------------------------------

### Run Default Entrypoint Example

Source: https://github.com/termux/proot-distro/blob/master/README.md

This example demonstrates how to run the default entrypoint of a container named 'hello-world'.

```sh
# Run the image's default entrypoint
proot-distro run hello-world
```

--------------------------------

### Installation Instructions

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/ARCHITECTURE.md

Provides commands for installing proot-distro from PyPI, from source using pip, and via the Termux package manager.

```bash
# From PyPI
pip install proot-distro

# From source (editable)
git clone https://github.com/termux/proot-distro
cd proot-distro
pip install -e .

# On Termux via package manager
pkg install proot-distro  # brings in proot as dependency

```

--------------------------------

### Run with Arguments Example

Source: https://github.com/termux/proot-distro/blob/master/README.md

This example demonstrates passing arguments to the entrypoint of an 'ubuntu' container, overriding the image's default Cmd.

```sh
# Pass arguments to the entrypoint (overrides image Cmd)
proot-distro run ubuntu -- /bin/echo hi
```

--------------------------------

### Install PRoot-Distro on Linux Host

Source: https://github.com/termux/proot-distro/blob/master/README.md

Install proot and then install PRoot-Distro using pip. Supports installation from PyPI or a local checkout.

```sh
# 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
```

--------------------------------

### Run and Print Proot Command Example

Source: https://github.com/termux/proot-distro/blob/master/README.md

This example shows how to retrieve and print the proot command line for a 'nextcloud' container without actually executing it.

```sh
# Print the proot command line without executing
proot-distro run nextcloud --get-proot-cmd
```

--------------------------------

### Install Container from Local Archive or URL

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/README.md

Installs a container image from a local OCI archive file or a remote URL.

```bash
# From local OCI archive
proot-distro install ./myimage.oci.tar

# From remote URL
proot-distro install https://example.com/image.tar.gz
```

--------------------------------

### Install PRoot-Distro

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/README.md

Install the proot-distro package using pip or the Termux package manager.

```bash
pip install proot-distro
```

```bash
pkg install proot-distro
```

--------------------------------

### Install from Private Registry

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/README.md

Install a container image from a private registry after setting the authentication environment variable. Ensure the image name and tag are correct.

```bash
proot-distro install ghcr.io/myorg/private-image:tag
```

--------------------------------

### Build with explicit tag and install

Source: https://github.com/termux/proot-distro/blob/master/README.md

Builds an image with a specific tag and installs it in a single step. This is a basic usage for creating and preparing an image.

```bash
proot-distro build -t myapp:1.0 --install-as myapp .
```

--------------------------------

### Install QEMU User-Mode for Cross-Architecture Builds

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/README.md

Install QEMU user-mode binaries to enable cross-architecture builds. This is necessary when building for an architecture different from the host system.

```bash
# Install QEMU user-mode
apt install qemu-user-static  # or pkg install qemu-user-aarch64 on Termux

# Or specify override
proot-distro build --emulator /path/to/qemu-aarch64-static --architecture aarch64 .
```

--------------------------------

### Basic PRoot-Distro CLI Usage

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/README.md

Demonstrates basic commands for installing, logging into, and building containers with proot-distro.

```bash
proot-distro install ubuntu:24.04
proot-distro login ubuntu
proot-distro build .
```

--------------------------------

### Install Ubuntu Container

Source: https://github.com/termux/proot-distro/blob/master/README.md

Install a specific Ubuntu version from Docker Hub. This is a quick way to get a containerized Linux distribution running.

```sh
proot-distro install ubuntu:24.04
```

--------------------------------

### Dockerfile Instruction AST Examples

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/types.md

Illustrates the structure of parsed Dockerfile instructions as Python dictionaries. Shows examples for FROM, RUN, COPY, and ENV instructions, including their common parameters and variations.

```python
{
    "instruction": "FROM",
    "image": "ubuntu:24.04",
    "platform": None,  # or "linux/amd64"
}

{
    "instruction": "RUN",
    "args": ["bash", "-c", "echo hello"],  # or shell form: ["sh", "-c", "..."]
    "form": "exec",  # or "shell"
}

{
    "instruction": "COPY",
    "src": ["file.txt"],
    "dst": "/app/",
    "from_stage": None,  # or stage name for multi-stage
    "chown": None,  # or "user:group"
    "chmod": None,  # or mode string
}

{
    "instruction": "ENV",
    "key": "APP_ENV",
    "value": "production",
}
```

--------------------------------

### List Installed Containers

Source: https://github.com/termux/proot-distro/blob/master/README.md

Displays all installed proot-distro containers. If no containers are installed, it suggests how to install one.

```sh
proot-distro list
Aliases: li, ls
```

--------------------------------

### Install Distribution with Explicit Name and Architecture

Source: https://github.com/termux/proot-distro/blob/master/README.md

Installs a Linux distribution from a local tarball, specifying a custom name and architecture.

```bash
proot-distro install /tmp/debian-arm.tar.xz --name debian --architecture arm
```

--------------------------------

### Run with Port Redirection Example

Source: https://github.com/termux/proot-distro/blob/master/README.md

This example shows how to run a container named 'nextcloud' with port redirection enabled, mapping host port 80 to container port 2080.

```sh
# Run with port redirection (so 80 → 2080)
proot-distro run nextcloud --redirect-ports
```

--------------------------------

### Install Dependencies and Run Tests

Source: https://github.com/termux/proot-distro/blob/master/tests/README.md

Installs necessary testing dependencies and provides commands to run the full offline test suite, security tests, or opt-in live tests.

```sh
# from the repo root
pip install -e '.[test]'      # or just have pytest available
python -m pytest -q           # full offline suite
python -m pytest tests/security -q   # just the containment tests
RUN_LIVE_TESTS=1 python -m pytest -q tests/live   # opt-in network/proot tests
```

--------------------------------

### Install PRoot-Distro from PyPI on Termux

Source: https://github.com/termux/proot-distro/blob/master/README.md

Install PRoot-Distro from PyPI on Termux after installing Python and proot. This method allows installing the latest published version.

```sh
pkg install python proot
pip install proot-distro
```

--------------------------------

### Login to Container

Source: https://github.com/termux/proot-distro/blob/master/README.md

Start an interactive shell session inside an installed container. This allows you to use the container as if it were a separate system.

```sh
proot-distro login ubuntu
```

--------------------------------

### Install Tools Inside a Distribution

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/README.md

Update package lists and install specific packages within a proot-distro environment. Ensure the distribution is already installed.

```bash
proot-distro login dev -- apt update
proot-distro login dev -- apt install -y build-essential git
```

--------------------------------

### Programmatically Install a Container

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/INDEX.md

Use the command_install function to install a container programmatically. Pass an argparse.Namespace object with required arguments like image and name.

```python
from proot_distro.commands.install import command_install
import argparse

args = argparse.Namespace(
    image="ubuntu:24.04",
    name="my-ubuntu",
    architecture=None,
    quiet=False,
)
command_install(args)
```

--------------------------------

### Install Container from Private Registry

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/README.md

Installs a container image from a private registry by setting the PD_DOCKER_AUTH environment variable with credentials.

```bash
export PD_DOCKER_AUTH=username:password
proot-distro install ghcr.io/myorg/private-image:tag
```

--------------------------------

### Proot Command Example

Source: https://github.com/termux/proot-distro/blob/master/README.md

This is an example of the proot command line used by PRoot-Distro to launch a container. It includes various flags for system call interception, path rewriting, and mounting host directories.

```sh
env PATH=… HOME=/root … \
  proot --kill-on-exit --link2symlink --sysvipc \
        --kernel-release=… -L \
        --change-id=0:0 \
        --rootfs=/…/containers/ubuntu/rootfs --cwd=/root \
        --bind=/dev --bind=/proc --bind=/sys \
        --bind=/storage --bind=/system --bind=/apex … \
        /bin/sh -l
```

--------------------------------

### Build Container Images

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/README.md

Demonstrates building container images with default or explicit tags, cross-architecture builds, outputting OCI tarballs, immediate installation after build, and using build arguments.

```bash
# Build with default tag
proot-distro build . 

# With explicit tag
proot-distro build -t myapp:1.0 .

# Cross-architecture
proot-distro build --architecture aarch64 -t myapp:arm .

# Output OCI tarball
proot-distro build -o myapp.oci.tar.gz .

# Install immediately after build
proot-distro build -t myapp:1.0 --install-as myapp .

# With build arguments
proot-distro build --build-arg HTTP_PROXY=$HTTP_PROXY -t myapp .
```

--------------------------------

### List Installed Containers

Source: https://github.com/termux/proot-distro/blob/master/README.md

Display a list of all containers that have been installed using PRoot-Distro. Shows the names of the available containers.

```sh
proot-distro list
```

--------------------------------

### CLI Flow - Proot Probe and Package Installation Offer

Source: https://github.com/termux/proot-distro/blob/master/CLAUDE.md

Details the proot probe process on Termux systems, including the offer to install packages.

```text
3. proot probe; on Termux + TTY, offers `pkg install`. **`build` and
   `push` are exempt**; `build` runs its own gate via
   `build_engine.needs_proot()` (True only with a RUN-family).
```

--------------------------------

### Install Container from Docker Hub

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/README.md

Installs a container image from Docker Hub, automatically detecting the platform. A custom name can also be assigned.

```bash
# From Docker Hub (auto-detects platform)
proot-distro install ubuntu:24.04

# With custom name
proot-distro install debian:bookworm --name my-debian
```

--------------------------------

### Build and Install Custom Image

Source: https://github.com/termux/proot-distro/blob/master/README.md

Build a new OCI image from a Dockerfile located in a specified context directory. The built image is then installed as a container.

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

--------------------------------

### Install Shell Completions for Bash

Source: https://github.com/termux/proot-distro/blob/master/README.md

Copies the Proot-Distro completion script to the user's local Bash completion directory.

```shell
# Bash, current user
mkdir -p ~/.local/share/bash-completion/completions
cp proot_distro/completions/proot-distro.bash \
   ~/.local/share/bash-completion/completions/proot-distro
```

--------------------------------

### List Installed Proot Distro Containers

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/api-reference/cli.md

Lists all installed containers, displaying their Name, Size, Architecture, and Image. Use the --quiet flag to print only the container names, one per line.

```bash
proot-distro list
proot-distro list --quiet
```

--------------------------------

### Install a container from a local OCI image layout archive

Source: https://github.com/termux/proot-distro/blob/master/README.md

Installs a container from a local tar archive that follows the OCI image layout specification. This format is typically produced by tools like `docker save`. Layers are cached, and `manifest.json` is written, enabling `reset` and `run` commands.

```bash
docker save myimage:latest -o myimage.oci.tar
proot-distro install ./myimage.oci.tar --name myimage
```

--------------------------------

### Install PRoot-Distro on Termux

Source: https://github.com/termux/proot-distro/blob/master/README.md

Install PRoot-Distro using the pkg package manager. This command also automatically installs proot as a dependency.

```sh
pkg install proot-distro
```

--------------------------------

### Install Shell Completions for Fish

Source: https://github.com/termux/proot-distro/blob/master/README.md

Copies the Proot-Distro completion script to the user's Fish completions directory.

```shell
# Fish, current user
mkdir -p ~/.config/fish/completions
cp proot_distro/completions/proot-distro.fish \
   ~/.config/fish/completions/proot-distro.fish
```

--------------------------------

### Install Container Command

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/api-reference/cli.md

Installs a container from a Docker/OCI image, URL, or local archive. Handles input type detection, image pulling, layer downloading, and filesystem assembly.

```bash
proot-distro install ubuntu:24.04
```

```bash
proot-distro install debian:bookworm --name my-debian
```

```bash
proot-distro install ./myimage.oci.tar
```

```bash
proot-distro install https://example.com/image.tar.gz --name myapp
```

--------------------------------

### Build a Custom Docker Image

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/README.md

Create a custom Linux image using a Dockerfile and then install it as a proot-distro container. The image is built locally and then registered.

```bash
# Create Dockerfile
cat > Dockerfile << EOF
FROM ubuntu:24.04
RUN apt-get update && apt-get install -y python3
COPY app.py /app/
WORKDIR /app
ENTRYPOINT ["python3", "app.py"]
EOF

# Build
proot-distro build -t myapp:1.0 .

# Install as container
proot-distro install myapp:1.0 --name myapp

# Run
proot-distro run myapp
```

--------------------------------

### Login to Container and Run Commands

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/README.md

Provides examples for logging into a container for an interactive shell, specifying a user, running a single command, setting environment variables, and mounting custom directories.

```bash
# Interactive shell
proot-distro login ubuntu

# As non-root user
proot-distro login ubuntu --user postgres

# Single command
proot-distro login ubuntu -- /bin/ls /etc

# With environment variables
proot-distro login ubuntu --env APP_ENV=production --env DEBUG=1

# With custom bindings
proot-distro login ubuntu --bind /data:/mnt/data
```

--------------------------------

### Set initial working directory

Source: https://github.com/termux/proot-distro/blob/master/README.md

Specify the starting directory within the container using '-w' or '--work-dir'. By default, it is the user's home directory.

```sh
proot-distro login -w /app mycontainer
```

--------------------------------

### Install a private Docker/OCI image with credentials

Source: https://github.com/termux/proot-distro/blob/master/README.md

Installs a private image from a registry by setting the PD_DOCKER_AUTH environment variable with username and password or PAT. This is required for private images on Docker Hub, GitHub Container Registry, and other OCI registries.

```bash
# Docker Hub private image
export PD_DOCKER_AUTH=myuser:mypassword
proot-distro install myuser/private-image:tag
```

```bash
# GitHub Container Registry — use your GitHub username and a PAT
# with the read:packages scope
export PD_DOCKER_AUTH=myuser:ghp_xxx
proot-distro install ghcr.io/myorg/private-image:tag
```

```bash
# Any other OCI registry
export PD_DOCKER_AUTH=myuser:mypassword
proot-distro install registry.example.com/private/image:tag
```

--------------------------------

### command_install

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/api-reference/cli.md

Installs a container from a Docker/OCI image, remote URL, or local archive. It handles image pulling, layer downloading, verification, and filesystem assembly.

```APIDOC
## command_install

### Description
Install a container from a Docker/OCI image, remote URL, or local archive.

### Method
N/A (CLI Command)

### Endpoint
N/A (CLI Command)

### Parameters
#### Arguments (argparse Namespace)
- **image** (str) - Required - Docker image reference, file path, or HTTP(S) URL
- **name** (str | None) - Optional - Custom container name (derived from image if omitted)
- **architecture** (str | None) - Optional - Override target architecture
- **quiet** (bool) - Optional - Suppress non-error output

### Request Example
```bash
proot-distro install ubuntu:24.04
proot-distro install debian:bookworm --name my-debian
proot-distro install ./myimage.oci.tar
proot-distro install https://example.com/image.tar.gz --name myapp
```

### Behavior
- Detects input type: Docker reference, local path, or URL
- For Docker images: pulls manifest, resolves platform, downloads layers, verifies SHA-256
- For local archives: detects format (plain tarball or OCI layout), extracts layers
- Assembles container filesystem with OCI whiteout semantics
- Writes manifest.json for OCI images (enables `reset` and `run`)
- Validates container name and exits if invalid

### Error cases
- Image/file not found
- Download fails (network error, 401/403 auth)
- Invalid container name
- zstd-compressed layers (unsupported by Python tarfile)
```

--------------------------------

### Install a container from a Docker/OCI registry

Source: https://github.com/termux/proot-distro/blob/master/README.md

Pulls a Docker or OCI image from a registry and creates a container from it. Supports official images, user images, and custom registries.

```bash
proot-distro install ubuntu:24.04
```

```bash
proot-distro install alpine:3.21 --name my-alpine
```

```bash
proot-distro install debian:bookworm --architecture aarch64
```

```bash
proot-distro install ghcr.io/myorg/myimage:latest
```

```bash
proot-distro install nextcloud:32
```

--------------------------------

### Install Shell Completions for Zsh

Source: https://github.com/termux/proot-distro/blob/master/README.md

Copies the Proot-Distro completion script to the user's Zsh completions directory and suggests adding it to the fpath.

```shell
# Zsh, current user
mkdir -p ~/.zsh/completions
cp proot_distro/completions/_proot-distro ~/.zsh/completions/_proot-distro
# and add 'fpath=(~/.zsh/completions $fpath)' to .zshrc before compinit
```

--------------------------------

### Run Container Entrypoint

Source: https://github.com/termux/proot-distro/blob/master/README.md

Executes the Entrypoint and/or Cmd defined in a container's Docker image manifest. Requires the container to be installed from an OCI image. Arguments passed after '--' override the image's Cmd.

```sh
proot-distro run [OPTIONS] CONTAINER [-- ARG ...]
```

--------------------------------

### Install a container from a local plain rootfs tarball

Source: https://github.com/termux/proot-distro/blob/master/README.md

Installs a container from a local tar archive containing a plain root filesystem. The archive can be compressed with gzip, bzip2, xz, or lzma. The tool automatically strips directory levels to form the root filesystem.

```bash
proot-distro install ./alpine-rootfs.tar.gz
```

--------------------------------

### Get Proot Emulator Arguments

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/api-reference/core.md

Generates arguments for proot to execute containers on different architectures using QEMU. Returns an empty list if no emulation is needed or if 32-bit native support is available.

```python
from proot_distro.arch import get_emulator_args

# Same architecture — no emulation
args = get_emulator_args("x86_64", "x86_64")  # []

# Cross-arch — needs QEMU
args = get_emulator_args("aarch64", "x86_64")
# Returns: ['-q', '/usr/bin/qemu-aarch64-static', ...]

# With override
args = get_emulator_args("arm", "x86_64", emulator_override="/usr/bin/qemu-arm-static")
```

--------------------------------

### Proot-distro CLI Entry Point

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/api-reference/cli.md

The main entry point for the proot-distro CLI, installed as 'proot-distro' and 'pd' console scripts. It handles signal routing, runtime checks, argument parsing, and command dispatch.

```python
def main() -> None:
    # CLI entry point for proot-distro. Installed as proot-distro and pd console scripts.
    # ... (implementation details)
    pass
```

```toml
[project.scripts]
proot-distro = "proot_distro.cli:main"
pd = "proot_distro.cli:main"
```

```python
import sys
from proot_distro.cli import main

if __name__ == "__main__":
    sys.argv = ["proot-distro", "list"]
    main()
```

--------------------------------

### Container Storage Structure

Source: https://github.com/termux/proot-distro/blob/master/CLAUDE.md

Illustrates the directory structure for storing container images and their root filesystems. Plain-tarball installs do not write manifest.json.

```text
containers/<name>/manifest.json   ← image_ref, arch, manifest, image_config
containers/<name>/rootfs/         ← assembled filesystem
```

--------------------------------

### Backup and Restore Container Data

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/README.md

Provides examples for backing up container data to a file, compressed pipe, or encrypted file, and restoring from these formats.

```bash
# Backup to file
proot-distro backup ubuntu --output ubuntu.tar.xz

# Backup to compressed pipe
proot-distro backup ubuntu | gzip > ubuntu.tar.gz

# Encrypted backup
proot-distro backup ubuntu | gpg -c > ubuntu.tar.gpg

# Restore from file
proot-distro restore ubuntu.tar.xz

# Restore from pipe
cat ubuntu.tar.xz | proot-distro restore

# Decrypt + restore
gpg -d ubuntu.tar.gpg | proot-distro restore
```

--------------------------------

### cli — Main Entry Point

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/api-reference/cli.md

The main entry point for the proot-distro CLI, installed as `proot-distro` and `pd` console scripts. It handles signal routing, runtime checks, argument parsing, and command dispatch.

```APIDOC
## main

### Description
CLI entry point for proot-distro. Installed as `proot-distro` and `pd` console scripts.

### Method
N/A (CLI Entry Point)

### Endpoint
N/A (CLI Entry Point)

### Parameters
N/A (Handled by argparse)

### Request Example
```python
import sys
from proot_distro.cli import main

if __name__ == "__main__":
    sys.argv = ["proot-distro", "list"]
    main()
```

### Response
N/A (None)

### Behavior
1. Signal handling: Routes SIGQUIT (Ctrl-\) to KeyboardInterrupt for consistent cleanup
2. Runtime checks:
   - Warns if running as root (non-fatal)
   - Rejects execution inside another proot (fatal)
   - Probes for `proot` availability; offers to install on Termux
3. Argument parsing:
   - Intercepts `-h`/`--help`/`--usage` before argparse to show per-command help
   - Validates unknown commands before parsing
   - Handles `--` separator for `login` and `run` subcommands
4. Dispatch:
   - Routes to the appropriate command handler via `_COMMAND_HANDLERS`
   - Validates required positional arguments
   - Sets quiet mode before dispatch
```

--------------------------------

### Push Container Images

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/README.md

Examples for pushing container images to Docker Hub or GitHub Container Registry, including authentication and specifying architecture for cross-compiled images.

```bash
# To Docker Hub
export PD_DOCKER_AUTH=username:password
proot-distro push username/myapp:1.0

# To GitHub Container Registry
export PD_DOCKER_AUTH=username:ghp_xxx
proot-distro push ghcr.io/myorg/myapp:1.0

# Specific architecture (cross-compiled)
proot-distro push --architecture aarch64 username/myapp:arm
```

--------------------------------

### Container Storage Directory Constant

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/configuration.md

Indicates the directory where all installed containers are stored. It includes a detailed layout example for container filesystems and manifests.

```python
CONTAINERS_DIR: str

# Path: $RUNTIME_DIR/containers

# Layout per container:
# containers/
#   ubuntu/
#     manifest.json     ← OCI manifest + image config (if from registry/OCI)
#     rootfs/           ← Container filesystem
#       bin/
#       etc/
#       usr/
#       ...
#   debian/
#     manifest.json
#     rootfs/
#       ...
#   alpine-custom/
#     rootfs/           ← No manifest if from plain tarball
#       ...
```

--------------------------------

### Start an interactive shell as a non-root user

Source: https://github.com/termux/proot-distro/blob/master/README.md

Log in as a specific user ('myuser') within the 'ubuntu' container. Ensure the user exists in the container or use a numeric UID.

```sh
proot-distro login ubuntu --user myuser
```

--------------------------------

### Legacy Container Storage Constant

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/configuration.md

Points to the old installation path for backwards compatibility. This directory's contents are automatically migrated to the new layout upon the first login.

```python
LEGACY_ROOTFS_DIR: str

# Old installation path for backwards compatibility. Path: $RUNTIME_DIR/installed-rootfs
```

--------------------------------

### Architecture Handling - Normalization and Emulation

Source: https://github.com/termux/proot-distro/blob/master/CLAUDE.md

Explains how architecture names are normalized and how emulation is handled for cross-architecture execution using QEMU.

```text
`normalize_arch()` accepts native names, bare Docker names
(`arm64`/`amd64`/`386`), and `linux/`-prefixed forms. Native 32-on-64:
`aarch64` runs `arm` when `personality(PER_LINUX32)` succeeds; `x86_64`
runs `i686` always. Otherwise `get_emulator_args()` selects
`qemu-<arch>` and binds Android system paths for QEMU's loader. proot's
`--kernel-release` `uname_m` field comes from `ARCH_UNAME_M`, not host
uname, so emulated containers self-report correctly.
```

--------------------------------

### Proot-Distro CLI Commands

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/MANIFEST.md

This section details the primary command-line interface commands available for interacting with proot-distro. These commands allow users to manage Linux distributions, including installation, removal, and execution of commands within them.

```APIDOC
## Proot-Distro CLI Commands

### Description

This section details the primary command-line interface commands available for interacting with proot-distro. These commands allow users to manage Linux distributions, including installation, removal, and execution of commands within them.

### Commands

- **`install`**: Install a distribution from an image, archive, or URL.
- **`remove`**: Delete a containerized distribution.
- **`rename`**: Rename an existing containerized distribution.
- **`reset`**: Reinstall a distribution from its manifest.
- **`login`**: Open a shell inside a containerized distribution.
- **`run`**: Execute the entrypoint or a specified command within a containerized distribution.
- **`list`**: List all installed containerized distributions.
- **`backup`**: Create an archive of a containerized distribution.
- **`restore`**: Restore a containerized distribution from an archive.
- **`copy`**: Copy files to or from a containerized distribution.
- **`sync`**: Synchronize files (changed-only) to or from a containerized distribution.
- **`build`**: Build an OCI image from a Dockerfile.
- **`push`**: Push a built OCI image to a registry.
- **`clear-cache`**: Delete cached data.
- **`help`**: Display help information.
```

--------------------------------

### CLI Flow - Signal Handling

Source: https://github.com/termux/proot-distro/blob/master/CLAUDE.md

Demonstrates how SIGQUIT is handled to trigger a KeyboardInterrupt, ensuring cleanup and partial file removal.

```text
1. SIGQUIT → `KeyboardInterrupt` so every existing `except` handles
   Ctrl-\\ like Ctrl-C (progress cleanup, partial-file removal,
   "Aborted by user").
```

--------------------------------

### Validate and Install Container Name

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/INDEX.md

Check if a container name is valid using is_valid_name before proceeding with installation. Use require_valid_name to enforce validation and exit if the name is invalid.

```python
from proot_distro.names import is_valid_name, require_valid_name

if is_valid_name("my-container"):
    install_container("my-container")

require_valid_name(user_input)  # Exits if invalid
```

--------------------------------

### Detect Installed Container Architecture

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/api-reference/core.md

Detect the CPU architecture of an installed container by probing ELF headers of common shell binaries. Accepts container names or rootfs paths.

```python
from proot_distro.arch import detect_installed_arch
arch = detect_installed_arch("ubuntu")
print(f"Container arch: {arch}")

# Or with full rootfs path:
arch = detect_installed_arch("/data/data/com.termux/files/usr/var/lib/proot-distro/containers/ubuntu/rootfs")
```

--------------------------------

### Display Help Information

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/api-reference/cli.md

Render and display help text for the proot-distro CLI. This command is invoked when no arguments are provided, or explicitly with 'help' or '-h'.

```bash
proot-distro

```

```bash
proot-distro help

```

```bash
proot-distro -h

```

```bash
pd --help

```

--------------------------------

### Build an Image Programmatically

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/api-reference/helpers.md

Demonstrates how to use BuildEngine to build an image from a Dockerfile and then write the resulting layers and configuration into an OCI-compliant tarball. This is useful for creating distributable container images.

```python
from proot_distro.helpers.build_engine import BuildEngine
from proot_distro.helpers.oci_writer import write_oci_tarball

# Configure build
engine = BuildEngine(
    dockerfile_path="./Dockerfile",
    context_dir=".",
    build_args={"BASE": "ubuntu:24.04"},
    target_stage=None,
)

# Execute build
manifest, image_config = engine.build()

# Write OCI tarball
layer_blobs = {
    digest: engine.get_layer(digest)
    for digest in manifest["layers"]
}
write_oci_tarball(
    manifest, image_config, layer_blobs,
    output_path="myimage.oci.tar.gz",
    compression="gzip"
)
```

--------------------------------

### Architecture Detection - ELF Header Reading

Source: https://github.com/termux/proot-distro/blob/master/CLAUDE.md

Details how the installed architecture is detected by reading the ELF e_machine from common shell binaries.

```text
`detect_installed_arch(rootfs)` reads ELF e_machine from common shell
binaries.
```

--------------------------------

### Restore Container from Backup

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/README.md

Restore a proot-distro container from a previously created backup file. This command can be run on any machine with proot-distro installed.

```bash
proot-distro restore backup.tar.xz
```

--------------------------------

### Get Container Manifest Path

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/api-reference/core.md

Returns the absolute path to a container's manifest.json file. Used to access container metadata.

```python
from proot_distro.paths import container_manifest
import json

manifest_path = container_manifest("ubuntu")
with open(manifest_path) as f:
    manifest = json.load(f)
```

--------------------------------

### get_emulator_args

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/api-reference/core.md

Retrieves proot emulator arguments for cross-architecture execution. It determines if emulation is needed based on container and device architectures and can optionally use a specified QEMU binary.

```APIDOC
## get_emulator_args

### Description
Return proot emulator arguments for cross-architecture execution. This function checks if emulation is necessary when running containers on different CPU architectures than the host.

### Function Signature
```python
get_emulator_args(dist_arch: str, device_arch: str, emulator_override: str = "") -> list
```

### Parameters
#### Path Parameters
* **dist_arch** (str) - Required - Target container architecture.
* **device_arch** (str) - Required - Host CPU architecture.
* **emulator_override** (str) - Optional - Custom QEMU binary path (overrides auto-detection). Defaults to `""`.

### Returns
list
- An empty list `[]` if no emulation is needed (e.g., architectures match, or 32-bit native support is available).
- A list containing emulator arguments, such as `["-q", "/usr/bin/qemu-aarch64-static", ...]`, if emulation is required.

### Behavior
- Returns `[]` when `dist_arch` is the same as `device_arch`.
- Returns `[]` when cross-arch execution is possible via 32-bit native support (e.g., running ARM on aarch64).
- Otherwise, returns QEMU user mode arguments suitable for proot.

### Example
```python
from proot_distro.arch import get_emulator_args

# Same architecture
args = get_emulator_args("x86_64", "x86_64")  # Returns: []

# Cross-architecture requiring QEMU
args = get_emulator_args("aarch64", "x86_64")
# Returns: ['-q', '/usr/bin/qemu-aarch64-static', ...]

# With an emulator override
args = get_emulator_args("arm", "x86_64", emulator_override="/usr/bin/qemu-arm-static")
```
```

--------------------------------

### Login to a Distribution

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/README.md

Access the shell of an installed distribution. This command is used for interactive sessions or running commands within the distribution's environment.

```bash
proot-distro login dev
```

--------------------------------

### Format Message with Colors

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/types.md

Demonstrates how to use the color dictionary (C) from proot_distro.message to format output strings with various colors and styles. Ensure colors are enabled for this to have an effect.

```python
from proot_distro.message import C, msg
msg(f"{C['BRED']}Error:{C['RST']} Something went wrong")
# Output in red bold: "Error: Something went wrong"

msg(f"{C['BGREEN']}[✓] Done{C['RST']}")
# Output in bold green: "[✓] Done"
```

--------------------------------

### Get Container Directory Path

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/api-reference/core.md

Retrieves the absolute path to a container's main directory. Used for accessing container-specific files and configurations.

```python
from proot_distro.paths import container_dir
cdir = container_dir("ubuntu")
# Returns: /data/data/com.termux/files/usr/var/lib/proot-distro/containers/ubuntu
```

--------------------------------

### Get ARCH_UNAME_M Mapping

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/api-reference/core.md

Access the mapping of proot-distro architecture names to the strings reported by `uname -m` inside containers. Useful for cross-referencing.

```python
from proot_distro.arch import ARCH_UNAME_M
# {'aarch64': 'aarch64', 'arm': 'armv7l', 'i686': 'i686', ...}
uname_m_value = ARCH_UNAME_M.get('aarch64')  # 'aarch64'
```

--------------------------------

### Get Proot-Distro Version

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/INDEX.md

Retrieves the program version string using Python's importlib.metadata. This is the standard way to access the version information.

```python
from proot_distro.constants import PROGRAM_VERSION
# Returns: version string from importlib.metadata or "rolling"
```

--------------------------------

### Run Command in Proot Distro Container

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/api-reference/cli.md

Executes the container image's Entrypoint and/or Cmd within proot, passing specified arguments. Reuses the same proot logic as the 'login' command. Container exits when the entrypoint finishes.

```bash
proot-distro run hello-world
proot-distro run nextcloud --redirect-ports
proot-distro run ubuntu -- /bin/echo hello
proot-distro run ubuntu -- bash -c "echo $USER"
```

--------------------------------

### File Operations with Containers

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/README.md

Shows how to copy files into or out of a container, perform recursive copies, and synchronize directories.

```bash
# Copy into container
proot-distro copy ./file.txt ubuntu:/root/file.txt

# Copy out of container
proot-distro copy ubuntu:/etc/resolv.conf ./resolv.conf

# Recursive copy
proot-distro copy --recursive ./app ubuntu:/opt/app

# Sync (copy only changed files)
proot-distro sync ./myapp ubuntu:/opt/myapp
```

--------------------------------

### detect_installed_arch

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/api-reference/core.md

Detects the CPU architecture of an installed proot-distro container by examining ELF headers of common shell binaries within the container's root filesystem.

```APIDOC
## detect_installed_arch

### Description
Detect the CPU architecture of an installed container by reading ELF headers.

### Method Signature
```python
detect_installed_arch(container_name_or_rootfs: str) -> str
```

### Parameters
#### Path Parameters
- **container_name_or_rootfs** (str) - Required - Container name or full path to rootfs directory

### Returns
str
- Architecture name if detected: `aarch64`, `arm`, `i686`, `x86_64`, `riscv64`
- `"unknown"` if detection fails

### Behavior:
- Accepts plain container name (resolved as `CONTAINERS_DIR/<name>/rootfs`)
- Accepts full path to rootfs directory
- Probes common shell binaries for ELF magic
- Reads `e_machine` field from ELF header
- Tries: `/usr/bin/bash`, `/usr/bin/sh`, `/bin/bash`, etc.

### Example:
```python
from proot_distro.arch import detect_installed_arch
arch = detect_installed_arch("ubuntu")
print(f"Container arch: {arch}")

# Or with full rootfs path:
arch = detect_installed_arch("/data/data/com.termux/files/usr/var/lib/proot-distro/containers/ubuntu/rootfs")
```
```

--------------------------------

### Build and push cross-architecture image

Source: https://github.com/termux/proot-distro/blob/master/README.md

Builds a cross-architecture image and then pushes it, specifying the architecture for both build and push operations. This ensures the correct architecture is targeted.

```bash
# Build a cross-arch image and push it
proot-distro build -t myuser/myapp:arm64 --architecture aarch64 .
proot-distro push --architecture aarch64 myuser/myapp:arm64
```

--------------------------------

### Backup and Restore a Portable Container

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/README.md

Create a portable backup of a proot-distro container and restore it on another machine. This allows for easy migration and sharing of environments.

```bash
# Backup container
proot-distro backup mycontainer --output backup.tar.xz

# Transfer to another machine (any OS, any arch)
scp backup.tar.xz otherhost:~

# Restore on other machine
ssh otherhost "proot-distro restore backup.tar.xz"
```

--------------------------------

### Build Image from Dockerfile

Source: https://github.com/termux/proot-distro/blob/master/README.md

Builds an OCI/Docker-compatible image from a Dockerfile in the specified build context path. The built image is stored in the local manifest cache.

```bash
proot-distro build [OPTIONS] [PATH]
```

--------------------------------

### BuildLock Usage with Context Manager

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/api-reference/core.md

Demonstrates acquiring and releasing a BuildLock using a 'with' statement, which is the recommended approach for managing build locks.

```python
from proot_distro.locking import BuildLock

with BuildLock("myapp:1.0", "aarch64", command="build") as lock:
    build_image("myapp:1.0", "aarch64")
```

--------------------------------

### Get Container Lock File Path

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/api-reference/core.md

Constructs the absolute path for a container's lock file. This is used to manage exclusive access during container operations.

```python
from proot_distro.locking import container_lock_path

container_name = "my_container"
lock_file = container_lock_path(container_name)
print(f"Lock file for {container_name}: {lock_file}")
```

--------------------------------

### Push image to Docker Hub with authentication

Source: https://github.com/termux/proot-distro/blob/master/README.md

Builds an image and then pushes it to Docker Hub using provided username and password for authentication. Requires `PD_DOCKER_AUTH` to be set.

```bash
# Docker Hub
export PD_DOCKER_AUTH=myuser:mypassword
proot-distro push myuser/myapp:1.0
```

--------------------------------

### Detect Host CPU Architecture

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/api-reference/core.md

Get the host CPU architecture in proot-distro's naming convention. This function reads `os.uname().machine` and normalizes ARM architectures.

```python
from proot_distro.arch import get_device_cpu_arch
host_arch = get_device_cpu_arch()
print(f"Running on {host_arch}")
```

--------------------------------

### Build OCI/Docker Image

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/api-reference/cli.md

Build an OCI/Docker-compatible image from a Dockerfile. Use this to create container images locally. Supports various options for build context, Dockerfile path, tagging, build arguments, architecture, and output formats.

```bash
proot-distro build .

```

```bash
proot-distro build -t myapp:1.0 --install-as myapp .

```

```bash
proot-distro build -f Dockerfile.prod -t myapp:prod --output myapp-prod.oci.tar .

```

```bash
proot-distro build --build-arg HTTP_PROXY=$HTTP_PROXY -t myapp .

```

```bash
proot-distro build --architecture aarch64 --target release -t myapp:arm .

```

--------------------------------

### Use the short alias 'pd login'

Source: https://github.com/termux/proot-distro/blob/master/README.md

This demonstrates the usage of the short alias 'pd' for 'proot-distro login'. It functions identically to the full command.

```sh
pd login ubuntu
```

--------------------------------

### OCI Manifest Cache Directory Constant

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/configuration.md

Specifies the directory for caching resolved single-architecture OCI manifests. These cached manifests are used by 'install', 'build', 'reset', and 'run' operations.

```python
MANIFEST_CACHE_DIR: str

# Path: $BASE_CACHE_DIR/oci_manifests

# Content: Manifest JSON files keyed by image reference + architecture

# Shared by: install, build, reset, run
```

--------------------------------

### Inspect the full proot command line

Source: https://github.com/termux/proot-distro/blob/master/README.md

Generate and display the complete 'env' + 'proot' command line that would be executed, without actually running the container. This is useful for debugging or understanding the underlying process.

```sh
proot-distro login ubuntu --get-proot-cmd
```

--------------------------------

### Container Path Derivation

Source: https://github.com/termux/proot-distro/blob/master/_autodocs/configuration.md

Demonstrates how to derive key directory paths for a container using functions from the proot_distro.paths module. These functions require the container name as an argument.

```python
from proot_distro.paths import container_dir, container_rootfs, container_manifest

# All require a container name
cdir = container_dir("ubuntu")           # CONTAINERS_DIR/ubuntu
rootfs = container_rootfs("ubuntu")      # CONTAINERS_DIR/ubuntu/rootfs
manifest = container_manifest("ubuntu")  # CONTAINERS_DIR/ubuntu/manifest.json
```