Architecture Maps

Termux

Architecture map of the Android terminal emulator — native execution, pseudo-terminal management, package ecosystem, and plugin IPC compiled from public sources.

Open Source Language: Java + C + Shell Platform: Android 7.0+ Updated: Mar 2026
01

Architecture Overview

Termux is a terminal emulator and Linux environment for Android that runs natively without root or emulation. Programs are cross-compiled against Android's Bionic libc and installed via apt/dpkg into an app-private prefix directory.

4
Gradle Modules
6
Plugin Apps
31
Build Steps
~20
PRoot Distros
4
CPU Archs
High-Level Architecture Stack
graph TD
    subgraph User["User Layer"]
        UI["TerminalView
(Android View)"]
        INPUT["Touch + Keyboard
Input Handling"]
    end

    subgraph App["Application Layer"]
        ACT["TermuxActivity"]
        SVC["TermuxService
(foreground service)"]
        SHELL["TermuxShellManager"]
    end

    subgraph Core["Terminal Engine"]
        SESS["TerminalSession"]
        EMU["TerminalEmulator"]
        BUF["TerminalBuffer"]
    end

    subgraph Native["Native / OS Layer"]
        JNI["JNI — termux.c
(PTY management)"]
        PTY["Pseudo-Terminal
/dev/ptmx"]
        EXEC["termux-exec
LD_PRELOAD"]
    end

    UI --> ACT
    INPUT --> ACT
    ACT --> SVC
    SVC --> SHELL
    SHELL --> SESS
    SESS --> EMU
    EMU --> BUF
    SESS --> JNI
    JNI --> PTY
    PTY --> EXEC

    style UI fill:#22324a,stroke:#56a7ff,color:#e7f0ff
    style INPUT fill:#22324a,stroke:#56a7ff,color:#e7f0ff
    style ACT fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style SVC fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style SHELL fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style SESS fill:#111c2d,stroke:#7ce6ff,color:#e7f0ff
    style EMU fill:#111c2d,stroke:#7ce6ff,color:#e7f0ff
    style BUF fill:#111c2d,stroke:#7ce6ff,color:#e7f0ff
    style JNI fill:#0d1421,stroke:#ffb24f,color:#e7f0ff
    style PTY fill:#0d1421,stroke:#ffb24f,color:#e7f0ff
    style EXEC fill:#0d1421,stroke:#ffb24f,color:#e7f0ff
02

App Module Architecture

The termux-app repository is a multi-module Gradle project. Four modules form a strict dependency chain, with termux-shared published via JitPack for plugin consumption.

Gradle Module Dependency Chain
graph LR
    APP["app/
Main APK"]
    SHARED["termux-shared/
Constants, IPC, Utils"]
    VIEW["terminal-view/
Android View"]
    EMU["terminal-emulator/
Pure Java Engine"]

    APP --> SHARED
    SHARED --> VIEW
    VIEW --> EMU

    PLUGINS["Plugin APKs
(via JitPack)"]
    PLUGINS -.-> SHARED

    style APP fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style SHARED fill:#22324a,stroke:#7ce6ff,color:#e7f0ff
    style VIEW fill:#22324a,stroke:#56a7ff,color:#e7f0ff
    style EMU fill:#111c2d,stroke:#ffb24f,color:#e7f0ff
    style PLUGINS fill:#2a1f3a,stroke:#c8a0c5,color:#e7f0ff

app/

Main Android application module. Contains TermuxActivity, TermuxService, RunCommandService, and TermuxShellManager. This is the APK entry point.

Application

terminal-emulator/

Pure Java terminal emulation engine with no Android dependencies. Contains TerminalEmulator, TerminalSession, TerminalBuffer, and JNI C code for PTY management.

Engine

terminal-view/

Android View subclass (TerminalView) that renders terminal emulator output. Handles touch gestures, text selection, and display.

View

termux-shared/

Shared constants (TermuxConstants with all hardcoded paths), socket management, IPC helpers, and file utilities. Published via JitPack for plugins.

Shared
03

Terminal Emulation & PTY

The terminal emulation stack operates across three layers: a JNI C layer for pseudo-terminal management, a Java TerminalSession with multi-threaded I/O, and an Android View for rendering.

Terminal Data Flow
graph LR
    subgraph Input["User Input"]
        KB["Keyboard /
Touch Events"]
    end

    subgraph View["TerminalView"]
        TV["Render Buffer
to Screen"]
    end

    subgraph Session["TerminalSession"]
        IN_T["Input Thread"]
        EMU_T["Emulation Thread"]
    end

    subgraph PTY["Pseudo-Terminal"]
        MASTER["PTY Master FD"]
        SLAVE["PTY Slave FD"]
    end

    subgraph Shell["Shell Process"]
        PROC["bash / zsh /
any program"]
    end

    KB --> TV
    TV -->|"write to master"| MASTER
    MASTER <-->|"kernel PTY pair"| SLAVE
    SLAVE --> PROC
    PROC --> SLAVE
    MASTER -->|"read output"| IN_T
    IN_T --> EMU_T
    EMU_T -->|"parse escapes"| TV

    style KB fill:#22324a,stroke:#56a7ff,color:#e7f0ff
    style TV fill:#22324a,stroke:#56a7ff,color:#e7f0ff
    style IN_T fill:#18263a,stroke:#7ce6ff,color:#e7f0ff
    style EMU_T fill:#18263a,stroke:#7ce6ff,color:#e7f0ff
    style MASTER fill:#0d1421,stroke:#ffb24f,color:#e7f0ff
    style SLAVE fill:#0d1421,stroke:#ffb24f,color:#e7f0ff
    style PROC fill:#111c2d,stroke:#39ffb6,color:#e7f0ff

JNI Layer (termux.c)

The C code opens /dev/ptmx with O_RDWR | O_CLOEXEC, configures the slave device (UTF-8 enabled, flow control disabled), sets initial window size via TIOCSWINSZ, then forks a child process that redirects all I/O to the slave PTY.

Exposes 5 JNI functions: createSubprocess, setPtyWindowSize, setPtyUTF8Mode, waitFor, and close.

Multi-Threaded I/O

TerminalSession uses separate threads: an input thread reads from the shell output stream and queues data, an emulation thread processes queued data through the TerminalEmulator (parsing escape sequences), and the main UI thread handles display via TerminalSessionClient callbacks.

04

Process Execution Model

Termux runs programs natively on Android — no emulation or containerization. Programs are compiled with Android NDK and linked against Bionic libc. Two distinct execution modes handle foreground and background tasks.

Execution Modes & Path Translation
graph TD
    subgraph Foreground["Foreground Sessions"]
        FG_CMD["User Command"]
        FG_JNI["JNI execvp()"]
        FG_PTY["PTY Pair"]
    end

    subgraph Background["Background Tasks"]
        BG_CMD["Plugin / Intent"]
        BG_JAVA["Runtime.exec()"]
        BG_PIPE["Pipe I/O"]
    end

    subgraph Intercept["Path Translation"]
        PRELOAD["termux-exec
LD_PRELOAD library"]
        REWRITE["Rewrites /bin/sh
to $PREFIX/bin/sh"]
    end

    FG_CMD --> FG_JNI
    FG_JNI --> FG_PTY
    FG_PTY --> PRELOAD

    BG_CMD --> BG_JAVA
    BG_JAVA --> BG_PIPE
    BG_PIPE --> PRELOAD

    PRELOAD --> REWRITE

    style FG_CMD fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style FG_JNI fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style FG_PTY fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style BG_CMD fill:#2a1f3a,stroke:#c8a0c5,color:#e7f0ff
    style BG_JAVA fill:#2a1f3a,stroke:#c8a0c5,color:#e7f0ff
    style BG_PIPE fill:#2a1f3a,stroke:#c8a0c5,color:#e7f0ff
    style PRELOAD fill:#111c2d,stroke:#ffb24f,color:#e7f0ff
    style REWRITE fill:#111c2d,stroke:#ffb24f,color:#e7f0ff
Key Constraints

External storage (/sdcard) is mounted with noexec — scripts must be passed to an interpreter. Android 10+ enforces W^X (Write XOR Execute) policy. SELinux restricts access to many /system/bin executables.

Why LD_PRELOAD?

Android has no /bin/ or /usr/bin/ directories. Rather than patching every script's shebang line, termux-exec globally intercepts the exec() family of functions to rewrite paths like /bin/sh to $PREFIX/bin/sh. Loaded automatically via $LD_PRELOAD for all child processes.

05

File System Layout

All Termux files live within the Android app sandbox at /data/data/com.termux/. The layout maps to Linux FHS as closely as possible, with all standard directories merged under $PREFIX.

Directory Tree Mapping
graph TD
    subgraph Sandbox["Android Sandbox: /data/data/com.termux/"]
        ROOT["files/
$TERMUX__ROOTFS"]
        USR["files/usr/
$PREFIX"]
        HOME["files/home/
$HOME"]
    end

    subgraph Prefix["$PREFIX Directories"]
        BIN["usr/bin/
/bin + /usr/bin + /sbin"]
        LIB["usr/lib/
/lib + /usr/lib"]
        ETC["usr/etc/
/etc"]
        TMP["usr/tmp/
$TMPDIR"]
        VAR["usr/var/
/var"]
        SHARE["usr/share/
/usr/share"]
    end

    subgraph Config["User Config: ~/.termux/"]
        PROPS["termux.properties"]
        COLORS["colors.properties"]
        FONT["font.ttf"]
    end

    ROOT --> USR
    ROOT --> HOME
    USR --> BIN
    USR --> LIB
    USR --> ETC
    USR --> TMP
    HOME --> Config

    style ROOT fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style USR fill:#22324a,stroke:#7ce6ff,color:#e7f0ff
    style HOME fill:#22324a,stroke:#7ce6ff,color:#e7f0ff
    style BIN fill:#111c2d,stroke:#56a7ff,color:#e7f0ff
    style LIB fill:#111c2d,stroke:#56a7ff,color:#e7f0ff
    style ETC fill:#111c2d,stroke:#56a7ff,color:#e7f0ff
    style TMP fill:#111c2d,stroke:#56a7ff,color:#e7f0ff
    style VAR fill:#111c2d,stroke:#56a7ff,color:#e7f0ff
    style SHARE fill:#111c2d,stroke:#56a7ff,color:#e7f0ff
    style PROPS fill:#2a1f3a,stroke:#c8a0c5,color:#e7f0ff
    style COLORS fill:#2a1f3a,stroke:#c8a0c5,color:#e7f0ff
    style FONT fill:#2a1f3a,stroke:#c8a0c5,color:#e7f0ff

Path Length Constraints

Resource Max Length Notes
Rootfs path 86 chars Linux syscall limit
PREFIX path 90 chars Linux syscall limit
Unix domain sockets 108 chars Kernel sockaddr_un limit
Shebang lines 340 chars With termux-exec
Package names 21 chars Convention for path budget

Storage Symlinks

Created by termux-setup-storage, these symlinks map Android directories into ~/storage/: shared (external root), downloads, dcim, pictures, music, and movies.

06

Bootstrap & Package Ecosystem

On first launch, Termux extracts a bootstrap ZIP containing the minimal rootfs (bash, apt, dpkg, coreutils). Packages use standard dpkg/apt tooling but are cross-compiled for Termux paths and Bionic libc.

Bootstrap & Package Install Flow
graph TD
    subgraph Bootstrap["First Launch Bootstrap"]
        VALIDATE["Validate Filesystem
+ Primary User"]
        EXTRACT["Extract ZIP to
$PREFIX-staging"]
        SYMLINKS["Process
SYMLINKS.txt"]
        ATOMIC["Atomic Rename
staging -> $PREFIX"]
        PERMS["Set Executable
Permissions"]
    end

    subgraph PkgMgmt["Package Management"]
        PKG["pkg install
(wrapper)"]
        APT["apt / dpkg"]
        REPO["HTTPS Repository
(mirrored globally)"]
    end

    VALIDATE --> EXTRACT
    EXTRACT --> SYMLINKS
    SYMLINKS --> ATOMIC
    ATOMIC --> PERMS
    PERMS --> PKG
    PKG --> APT
    APT --> REPO

    style VALIDATE fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style EXTRACT fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style SYMLINKS fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style ATOMIC fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style PERMS fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style PKG fill:#22324a,stroke:#7ce6ff,color:#e7f0ff
    style APT fill:#22324a,stroke:#7ce6ff,color:#e7f0ff
    style REPO fill:#111c2d,stroke:#56a7ff,color:#e7f0ff

main

Primary package repository (packages/) containing core tools, languages, libraries, and utilities.

Repository

root-packages

Packages that require root access to function (root-packages/).

Repository

x11-packages

X11 / GUI packages for graphical applications (x11-packages/).

Repository
Why Standard Debian Packages Don't Work

Termux is not FHS-compliant. All paths are relocated to $PREFIX during compilation. Binaries are linked against Bionic libc (not glibc), and the flat $PREFIX/bin merges /bin, /sbin, /usr/bin, and /usr/sbin.

07

Build Infrastructure

The termux-packages repository contains a 31-step cross-compilation pipeline. Each package defines a build.sh script with source URL, checksum, dependencies, and optional build hooks.

Build Pipeline (Key Steps)
graph TD
    subgraph Setup["Setup Phase"]
        S1["Setup Variables"]
        S2["Get Dependencies"]
        S3["Download Source"]
        S4["Setup Toolchain
(NDK cross-compiler)"]
    end

    subgraph Build["Build Phase"]
        S5["Patch Package
(apply *.patch files)"]
        S6["Configure
(autotools/CMake/Meson)"]
        S7["Compile"]
        S8["Install to Prefix"]
    end

    subgraph Package["Package Phase"]
        S9["Strip Binaries /
Create Subpackages"]
        S10["Generate .deb"]
    end

    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S5
    S5 --> S6
    S6 --> S7
    S7 --> S8
    S8 --> S9
    S9 --> S10

    style S1 fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style S2 fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style S3 fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style S4 fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style S5 fill:#22324a,stroke:#7ce6ff,color:#e7f0ff
    style S6 fill:#22324a,stroke:#7ce6ff,color:#e7f0ff
    style S7 fill:#22324a,stroke:#7ce6ff,color:#e7f0ff
    style S8 fill:#22324a,stroke:#7ce6ff,color:#e7f0ff
    style S9 fill:#111c2d,stroke:#ffb24f,color:#e7f0ff
    style S10 fill:#111c2d,stroke:#ffb24f,color:#e7f0ff

Supported Architectures

aarch64

Default build target. ARM 64-bit — most modern Android devices.

arm

ARM 32-bit for older devices.

x86_64

Intel/AMD 64-bit for Chromebooks and x86 Android devices.

i686

Intel/AMD 32-bit legacy support.

Build System Auto-Detection

The build system recognizes autotools (configure), CMake (CMakeLists.txt), and Meson (meson.build). Helper functions exist for Rust, Go, and Node.js builds. The recommended environment is the Docker image ghcr.io/termux/package-builder launched via ./scripts/run-docker.sh.

08

PRoot & proot-distro

PRoot is a user-space chroot that uses ptrace() to intercept system calls and rewrite file paths. No root required. proot-distro manages full Linux distribution installations on top of it.

PRoot Syscall Interception
graph TD
    subgraph Guest["Guest Distro (e.g. Ubuntu)"]
        GPROC["Process calls
open('/etc/apt/...')"]
    end

    subgraph PRoot["PRoot (ptrace)"]
        INTERCEPT["Intercept Syscall"]
        REWRITE["Rewrite Path
/etc -> /data/.../rootfs/etc"]
        FAKEROOT["Fake UID/GID
(-0 flag)"]
    end

    subgraph Host["Android / Termux"]
        KERNEL["Linux Kernel"]
        FS["Actual Filesystem"]
    end

    GPROC --> INTERCEPT
    INTERCEPT --> REWRITE
    INTERCEPT --> FAKEROOT
    REWRITE --> KERNEL
    KERNEL --> FS

    style GPROC fill:#1a3530,stroke:#39ffb6,color:#e7f0ff
    style INTERCEPT fill:#22324a,stroke:#ffb24f,color:#e7f0ff
    style REWRITE fill:#22324a,stroke:#ffb24f,color:#e7f0ff
    style FAKEROOT fill:#22324a,stroke:#ffb24f,color:#e7f0ff
    style KERNEL fill:#0d1421,stroke:#56a7ff,color:#e7f0ff
    style FS fill:#0d1421,stroke:#56a7ff,color:#e7f0ff

proot-distro Operations

Command Description
install Download and extract distro rootfs tarball
login Enter the distro environment via PRoot
backup / restore Archive and restore distro installations
remove / reset Delete or factory-reset a distro
rename Rename an installed distro
Limitation

PRoot cannot perform real privilege escalation. Kernel and hardware operations requiring actual root will fail. The -0 flag only fakes the UID to appear as root inside the chroot environment.

Supported Distributions (~20)

Alpine, Arch Linux, Debian, Ubuntu, Fedora, Void Linux, OpenSUSE, Rocky Linux, AlmaLinux, Deepin, and more. Architecture support varies by distro (aarch64, arm, i686, x86_64, riscv64).

09

Plugin System & IPC

Termux plugins are separate Android APKs sharing the same sharedUserId (com.termux), giving them direct filesystem access. Inter-process communication uses Unix domain sockets and Android Intents.

Termux:API Command Flow
graph LR
    subgraph CLI["Terminal"]
        CMD["termux-battery-status
(shell script)"]
        BIN["termux-api
(native binary)"]
    end

    subgraph IPC["IPC Layer"]
        SOCK["Unix Domain
Sockets (in/out)"]
        INTENT["Android Intent
+ socket addresses"]
    end

    subgraph API["Termux:API App"]
        RECV["TermuxApiReceiver
(BroadcastReceiver)"]
        HANDLER["API Handler
(e.g. BatteryStatusAPI)"]
        RETURN["ResultReturner
(JSON output)"]
    end

    CMD --> BIN
    BIN --> SOCK
    SOCK --> INTENT
    INTENT --> RECV
    RECV --> HANDLER
    HANDLER --> RETURN
    RETURN -->|"via output socket"| SOCK

    style CMD fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style BIN fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style SOCK fill:#22324a,stroke:#ffb24f,color:#e7f0ff
    style INTENT fill:#22324a,stroke:#ffb24f,color:#e7f0ff
    style RECV fill:#2a1f3a,stroke:#c8a0c5,color:#e7f0ff
    style HANDLER fill:#2a1f3a,stroke:#c8a0c5,color:#e7f0ff
    style RETURN fill:#2a1f3a,stroke:#c8a0c5,color:#e7f0ff

Termux:API

Bridge to 30+ Android system APIs: battery, camera, sensors, clipboard, notifications, SMS, location, and more.

com.termux.api

Termux:Boot

Runs scripts from ~/.termux/boot/ at device boot for persistent daemons and services.

com.termux.boot

Termux:Float

Floating terminal window overlay for multitasking with other Android apps.

com.termux.window

Termux:Styling

Color scheme and font selector with Powerline-ready font options.

com.termux.styling

Termux:Widget

Home screen shortcuts and widgets for scripts in ~/.shortcuts/.

com.termux.widget

Termux:Tasker

Integration with Tasker/Locale for automation workflows.

com.termux.tasker

External App Integration

Non-plugin apps can send RUN_COMMAND intents to RunCommandService, which validates permissions (requires PROP_ALLOW_EXTERNAL_APPS=true in termux.properties) and forwards commands to TermuxService. Content providers expose files via content://com.termux.files/ and content://com.termux.documents/.

10

Session & Service Management

TermuxService is a foreground Android Service that persists independently of the UI, managing interactive terminal sessions and background tasks. Sessions survive activity destruction.

Session Lifecycle
graph TD
    subgraph Activity["TermuxActivity"]
        BIND["ServiceConnection"]
        DRAWER["Session Drawer
(multiple tabs)"]
        CLIENTS["ViewClient +
SessionClient"]
    end

    subgraph Service["TermuxService (foreground)"]
        SESSIONS["TermuxSession List
(interactive terminals)"]
        TASKS["AppShell List
(background tasks)"]
        LOCKS["Wake Lock +
WiFi Lock"]
        NOTIF["Foreground Notification
(session/task counts)"]
    end

    subgraph Create["Session Creation"]
        EXCMD["ExecutionCommand"]
        SHELLMGR["TermuxShellManager"]
        JNI["JNI createSubprocess"]
    end

    BIND --> Service
    DRAWER --> SESSIONS
    CLIENTS --> SESSIONS
    EXCMD --> SHELLMGR
    SHELLMGR --> SESSIONS
    SHELLMGR --> TASKS
    SHELLMGR --> JNI

    style BIND fill:#22324a,stroke:#56a7ff,color:#e7f0ff
    style DRAWER fill:#22324a,stroke:#56a7ff,color:#e7f0ff
    style CLIENTS fill:#22324a,stroke:#56a7ff,color:#e7f0ff
    style SESSIONS fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style TASKS fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style LOCKS fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style NOTIF fill:#18263a,stroke:#39ffb6,color:#e7f0ff
    style EXCMD fill:#111c2d,stroke:#7ce6ff,color:#e7f0ff
    style SHELLMGR fill:#111c2d,stroke:#7ce6ff,color:#e7f0ff
    style JNI fill:#111c2d,stroke:#ffb24f,color:#e7f0ff
Android 10+ Restriction

Background TermuxService cannot start foreground terminal sessions until the user taps the Termux notification. Mitigated since Termux v0.100 by requesting "Draw Over Apps" permission.

11

Input Handling

Termux bridges Android's touch-first input model to a keyboard-driven terminal environment through hardware key events, volume key shortcuts, a configurable extra keys row, and a text input view with autocorrect.

Hardware Keyboard

Standard Android key event handling via TerminalView.onKeyDown()/onKeyUp(). Full Ctrl, Alt, Esc, arrow keys, and function key support.

Volume Key Shortcuts

Volume Down acts as Ctrl (e.g., Vol Down + L = Ctrl+L). Volume Up + Q/K toggles the extra keys row.

Extra Keys Row

Configurable via termux.properties as JSON arrays. Supports multi-row layouts, macro keys, and popup keys (long-press alternatives).

Text Input View

Native Android text input with autocorrect, prediction, and swipe typing that pastes completed text into the terminal.

12

Glossary

APKAndroid Package Kit
BionicAndroid's C standard library (libc)
CPRSCross-compilation prefix relocation
dpkgDebian package manager
FHSFilesystem Hierarchy Standard
FDFile Descriptor
IPCInter-Process Communication
JNIJava Native Interface
LD_PRELOADDynamic linker library injection
NDKNative Development Kit (Android)
PRootPortable Root (ptrace-based chroot)
PTYPseudo-Terminal
SELinuxSecurity-Enhanced Linux
W^XWrite XOR Execute (memory policy)
$PREFIX/data/data/com.termux/files/usr
$HOME/data/data/com.termux/files/home
Diagram
100%
Scroll to zoom · Drag to pan · Esc to close