# Termux User Guide

Termux is an Android terminal emulator and Linux environment app. It gives you a real command line on your phone or tablet — Bash or Zsh shell, hundreds of common Unix utilities, and access to more than 1,000 installable packages — **without root and without any special device setup**.

This guide covers the Termux *application*: installing it, running terminal sessions, customizing the keyboard and terminal, sharing files with other apps, and driving Termux from automation tools. The software you run *inside* Termux (Python, Git, SSH, compilers, and so on) is delivered separately through the [termux-packages](https://github.com/termux/termux-packages) project and installed with the `pkg` command once Termux is running.

> [!IMPORTANT]
> This is the documentation for the Termux Android app — its user interface and terminal emulation. It is **not** the documentation for individual command-line programs. For package management and the Linux userland, see the [Termux Wiki](https://wiki.termux.com/wiki/).

---

## 1. Quick Start

1. Install the Termux APK from a single trusted source (see [Installation](#3-installation)). F-Droid is recommended for most users.
2. Open Termux. On first launch it shows an **"Installing…"** progress dialog while it unpacks the base system (the *bootstrap*). Wait for it to finish.
3. When the dialog closes you are dropped at a shell prompt in your home directory:

   ```text
   ~ $
   ```

4. Update the package lists and install something useful:

   ```bash
   pkg upgrade
   pkg install git python openssh
   ```

5. Try it out:

   ```bash
   python --version
   ```

   ```text
   Python 3.x.x
   ```

> [!TIP]
> Long-press anywhere on the terminal to open the **context menu**. This is the gateway to almost everything the app offers: a new session, styling, settings, the help wiki, and the issue reporter.

> [!NOTE]
> The keyboard row above the terminal — `ESC`, `CTRL`, `ALT`, arrows, and more — is the **extra keys** toolbar. Those keys do not exist on a normal touch keyboard but are essential for terminal work. You can fully customize this row; see [Customizing the Extra Keys](#62-customizing-the-extra-keys-row).

---

## 2. Requirements

| Requirement | Detail |
|---|---|
| Android version | **Android 7.0 (API 24) or higher** for full app + package support. Android 5/6 receive the app only (no package updates) via GitHub builds. |
| Architecture | `arm64-v8a`, `armeabi-v7a`, `x86`, `x86_64` (universal and per-architecture APKs are published). |
| Root | **Not required.** Termux runs entirely inside its own private app data directory. |
| Free storage | ~120–180 MB for the app plus the bootstrap, before you install any extra packages. |
| User profile | Termux must be installed and run as the **primary device user**. Secondary users, work profiles, and installation on a portable SD card are not supported and will fail at startup. |

> [!WARNING]
> Termux can be unstable on **Android 12 and higher** because Android aggressively kills background ("phantom") processes and processes using excess CPU. You may see `[Process completed (signal 9) - press Enter]` even though you never stopped the process yourself. See [Troubleshooting: phantom process killing](#error-process-completed-signal-9---press-enter).

---

## 3. Installation

Termux is distributed as a standard Android APK. **Pick one source and use it for everything**, because the app and its plugins are signed with source-specific keys.

> [!CAUTION]
> The Termux app and every plugin share the Android `sharedUserId` `com.termux`. All installed APKs **must be signed with the same key**, which means they must all come from the **same source**. Mixing an app from F-Droid with a plugin from GitHub causes installation errors such as `App not installed`, `INSTALL_FAILED_UPDATE_INCOMPATIBLE`, or `signatures do not match previously installed version`. If you switch sources, uninstall everything Termux-related first.

### 3.1 F-Droid (recommended)

Download the APK directly from the [F-Droid Termux page](https://f-droid.org/en/packages/com.termux/) using the **Download APK** link — you do not need the F-Droid client app.

- Only a **universal** APK is offered (works on all architectures); install size is ~180 MB.
- F-Droid builds appear a few days to a week after a GitHub release, because F-Droid builds and signs them independently.

=== "Install via F-Droid client"

    1. Open the F-Droid app.
    2. Search for `Termux`.
    3. Tap **Install**.
    4. Pull down to refresh the **Updates** tab to check for new versions later.

=== "Install the APK directly"

    1. Open the [F-Droid Termux page](https://f-droid.org/en/packages/com.termux/) in a browser.
    2. Scroll to the latest version and tap **Download APK**.
    3. Open the downloaded file and confirm the install (you may need to allow installs from your browser).

> [!TIP]
> The F-Droid client often will not notify you of updates automatically. Make sure battery optimizations are disabled for it (see [dontkillmyapp.com](https://dontkillmyapp.com/)), and manually pull-to-refresh the Updates tab.

### 3.2 GitHub

Get APKs from [GitHub Releases](https://github.com/termux/termux-app/releases) (version `>= 0.118.0`) or from the [Build action artifacts](https://github.com/termux/termux-app/actions) for bleeding-edge commits.

- **For Android 7 and higher, install only `apt-android-7` variants. For Android 5/6, install only `apt-android-5` variants.**
- Both universal (~180 MB) and per-architecture (~120 MB) APKs are published.
- GitHub builds are `debuggable` and are compatible with each other but **not** with F-Droid or Play Store builds.

> [!CAUTION]
> GitHub APKs are signed with a **public test key** that is shared with the community. This is *not* an official developer key — anyone can use it to build an installable "update." Only trust GitHub builds downloaded directly from [github.com/termux/termux-app](https://github.com/termux/termux-app). Be extremely wary of Termux builds shared on Telegram, social media, or other channels.

### 3.3 Google Play Store (experimental)

An experimental Play Store build exists for Android 11+ but is under active development with missing functionality and known bugs. It is built from a [separate repository](https://github.com/termux-play-store/) and most users should prefer F-Droid or GitHub. Report Play Store issues to that repository, not the main one.

---

## 4. Uninstallation

To remove Termux completely you must uninstall **the app and every plugin** (they are separate APKs):

- [ ] Termux
- [ ] Termux:API
- [ ] Termux:Boot
- [ ] Termux:Float
- [ ] Termux:Styling
- [ ] Termux:Tasker
- [ ] Termux:Widget

Go to **Android Settings → Applications**, search for `termux`, and uninstall each one. Even if you think you never installed a plugin, check the list anyway.

> [!TIP]
> Consider [backing up Termux](https://wiki.termux.com/wiki/Backing_up_Termux) before uninstalling — your installed packages and home directory are otherwise lost.

---

## 5. Everyday Usage

### 5.1 The terminal screen

When Termux is open you see three things:

```text
┌─────────────────────────────────────┐
│                                     │  ← terminal output area
│   ~ $ █                             │     (your shell session)
│                                     │
├─────────────────────────────────────┤
│ ESC  /  -  HOME  UP  END  PGUP      │  ← extra keys toolbar
│ TAB CTRL ALT LEFT DOWN RIGHT PGDN   │     (two rows by default)
└─────────────────────────────────────┘
   ☰ (swipe from left edge = session drawer)
```

- **Output area** — your live shell. Tap to place the cursor; long-press to select text or open the context menu.
- **Extra keys toolbar** — terminal keys missing from the soft keyboard. Fully customizable.
- **Navigation drawer** — swipe in from the **left edge** to reveal the list of open sessions, a **NEW SESSION** button, a **settings** button, and a **keyboard toggle** button.

### 5.2 Working with sessions

Termux supports multiple independent terminal sessions running at once.

| Action | How |
|---|---|
| Open the session drawer | Swipe from the left edge of the screen |
| Create a new session | Tap **NEW SESSION** in the drawer |
| Create a **named** session | Long-press **NEW SESSION**, type a name |
| Create a **failsafe** session | Long-press **NEW SESSION** → failsafe option (starts a minimal shell that bypasses your startup files) |
| Switch sessions | Tap a session in the drawer |
| Rename / view a session | Long-press a session in the drawer |
| Close a session | Type `exit` or press `Ctrl+D` in the shell |

> [!NOTE]
> A **failsafe session** launches a bare shell without sourcing your profile scripts. Use it to recover when a broken `~/.bashrc`, `~/.profile`, or `~/.zshrc` prevents normal sessions from starting.

> [!TIP]
> You can switch sessions and trigger session actions with hardware-keyboard shortcuts. By default these are disabled and must be enabled in `termux.properties`; see [Hardware keyboard shortcuts](#64-hardware-keyboard-shortcuts).

### 5.3 The terminal context menu

Long-press the terminal output to open the context menu. The available actions are:

| Menu item | What it does |
|---|---|
| **Select URL** | Lists URLs found in the visible transcript so you can open or copy one |
| **Share transcript** | Shares the entire scrollback buffer to another app |
| **Share selected text** | Appears when text is selected; shares just that text |
| **Autofill username / password** | Appears when an Android autofill provider is active; inserts a stored credential |
| **Reset terminal** | Resets the emulator state (clears odd colors/modes without killing the shell) |
| **Kill process** `(pid …)` | Terminates the foreground session's process |
| **Style** | Opens **Termux:Styling** (if installed) to change colors and fonts |
| **Keep screen on** | Toggles a wake-lock so the screen does not sleep |
| **Help** | Opens the Termux Wiki in the in-app viewer |
| **Settings** | Opens Termux app settings |
| **Report issue** | Generates a debug report from the current transcript for bug reports |

### 5.4 Copy, paste, and text selection

- **Select text** — long-press a word, then drag the selection handles.
- **Copy** — use the selection action bar that appears, or **Share selected text** from the context menu.
- **Paste** — long-press in the terminal and choose paste, or use the toolbar text-input field.

> [!WARNING]
> Pasting certain raw control characters (for example a literal ESC, Unicode 27) can crash the terminal. Avoid pasting binary or control-laden content directly into the prompt. ([Known issue #5119](https://github.com/termux/termux-app/issues/5119).)

### 5.5 Installing software with `pkg`

Once you have a shell, install programs with the `pkg` front-end (a wrapper around `apt`):

```bash
pkg upgrade               # refresh package lists and upgrade installed packages
pkg install <name>        # install a package
pkg uninstall <name>      # remove a package
pkg search <term>         # search available packages
pkg list-installed        # list what you have
```

For example, to set up a small development environment:

```bash
pkg install git python nodejs openssh nano
```

```text
Reading package lists... Done
...
```

> [!NOTE]
> If `apt`/`pkg` reports `repository is under maintenance or down`, follow the [Package Management guide](https://github.com/termux/termux-packages/wiki/Package-Management). Packages themselves are maintained in the separate `termux-packages` repository, not in the app.

### 5.6 Accessing your device's shared storage

By default Termux only sees its own private files. To reach your photos, downloads, and other shared storage, run:

```bash
termux-setup-storage
```

Android shows a permission prompt; grant it. Termux then creates a `~/storage` directory containing symlinks into shared storage:

| Symlink | Points to |
|---|---|
| `~/storage/shared` | Primary shared storage root (`/storage/emulated/0`) |
| `~/storage/documents` | Documents |
| `~/storage/downloads` | Downloads |
| `~/storage/dcim` | Camera (DCIM) |
| `~/storage/pictures` | Pictures |
| `~/storage/music` | Music |
| `~/storage/movies` | Movies |
| `~/storage/podcasts` | Podcasts |
| `~/storage/audiobooks` | Audiobooks (Android 10+) |
| `~/storage/external-N` | App-specific external dirs |
| `~/storage/media-N` | App-specific media dirs |

```bash
ls ~/storage/downloads
```

```text
report.pdf  photo.jpg  ...
```

---

## 6. Customizing Termux

Termux's main customization surface for end users is a plain-text file named **`termux.properties`**. The app reads it from the first of these two locations that exists:

1. `~/.termux/termux.properties` *(primary)*
2. `~/.config/termux/termux.properties` *(secondary)*

After editing the file, reload it **without restarting** by long-pressing the terminal and choosing **More → Style**, or simply reopen the app. Lines starting with `#` are comments. Boolean properties accept `true`/`false`.

> [!TIP]
> Create the file if it does not exist:
> ```bash
> mkdir -p ~/.termux && nano ~/.termux/termux.properties
> ```

### 6.1 Common terminal settings

| Property | Values | Default | Effect |
|---|---|---|---|
| `bell-character` | `vibrate`, `beep`, `ignore` | `vibrate` | What the terminal bell (`\a`) does |
| `terminal-cursor-style` | `block`, `underline`, `bar` | `block` | Cursor shape |
| `terminal-cursor-blink-rate` | `0` or `100`–`2000` | `0` (off) | Cursor blink interval in ms; `0` disables blinking |
| `terminal-transcript-rows` | integer (within engine limits) | engine default | Scrollback buffer size |
| `terminal-margin-horizontal` | `0`–`100` | `3` | Left/right terminal margin in dp |
| `terminal-margin-vertical` | `0`–`100` | `0` | Top/bottom terminal margin in dp |
| `terminal-toolbar-height` | `0.4`–`3` | `1` | Height scale factor for the extra-keys toolbar |
| `fullscreen` | `true`/`false` | `false` | Run the terminal in fullscreen |
| `night-mode` | `true`, `false`, `system` | `system` | Force dark/light theme or follow the system |
| `hide-soft-keyboard-on-startup` | `true`/`false` | `false` | Start with the soft keyboard hidden |
| `terminal-onclick-url-open` | `true`/`false` | `false` | Open URLs on a single tap instead of via the menu |

Example `termux.properties`:

```properties
# Quieter bell and a thin blinking cursor
bell-character = ignore
terminal-cursor-style = bar
terminal-cursor-blink-rate = 500

# Follow the system dark theme, keep a small margin
night-mode = system
terminal-margin-horizontal = 6
```

### 6.2 Customizing the extra keys row

The `extra-keys` property defines the toolbar above the keyboard. It is a JSON-like matrix of rows; each entry is a key name or an object with a `key` and optional `popup` (the action when you swipe up on that button).

Default value:

```properties
extra-keys = [['ESC','/',{key: '-', popup: '|'},'HOME','UP','END','PGUP'], \
              ['TAB','CTRL','ALT','LEFT','DOWN','RIGHT','PGDN']]
```

A simpler single row:

```properties
extra-keys = [[ESC, TAB, CTRL, ALT, {key: '-', popup: '|'}, DOWN, UP]]
```

**Recognized key names** include: `SPACE`, `ESC`, `TAB`, `HOME`, `END`, `PGUP`, `PGDN`, `INS`, `DEL`, `BKSP`, `UP`, `DOWN`, `LEFT`, `RIGHT`, `ENTER`, and `F1`–`F12`, plus modifier buttons `CTRL`, `ALT`, `FN`, `SHIFT`, and special buttons such as `DRAWER`, `KEYBOARD`, `PASTE`, and `SCROLL`. Friendly aliases are accepted too — for example `ESCAPE`→`ESC`, `CONTROL`→`CTRL`, `PAGEUP`→`PGUP`, `BACKSPACE`→`BKSP`, `DELETE`→`DEL`.

Related properties:

| Property | Values | Default | Effect |
|---|---|---|---|
| `extra-keys-style` | `default`, `arrows-only`, `arrows-all`, `all`, `none`, … | `default` | Glyph style for the key labels (e.g. arrow symbols) |
| `extra-keys-text-all-caps` | `true`/`false` | `true` | Capitalize button labels |

> [!TIP]
> The repetitive keys `UP`, `DOWN`, `LEFT`, `RIGHT`, `BKSP`, `DEL`, `PGUP`, and `PGDN` auto-repeat when held — handy for navigating long command history or files.

### 6.3 Key behavior settings

| Property | Values | Default | Effect |
|---|---|---|---|
| `back-key` | `back`, `escape` | `back` | Make the Android Back button send ESC instead of closing |
| `volume-keys` | `virtual`, `volume` | `virtual` | `virtual` lets Volume-Down act as a Ctrl-style modifier; `volume` restores normal volume control |
| `soft-keyboard-toggle-behaviour` | `show/hide`, `enable/disable` | `show/hide` | What the keyboard-toggle button does |
| `enforce-char-based-input` | `true`/`false` | `false` | Workaround for devices (e.g. some Samsung) where letters do not appear until Enter |
| `ctrl-space-workaround` | `true`/`false` | `false` | Fix `Ctrl+Space` on ROMs where it does not work |

> [!NOTE]
> With the default `volume-keys = virtual`, **Volume-Down acts as an extra modifier key** for terminal shortcuts (for example Volume-Down + C). If you would rather keep normal volume control inside Termux, set `volume-keys = volume`.

### 6.4 Hardware keyboard shortcuts

If you connect a physical keyboard, you can bind session actions. Assign a letter to each shortcut key:

| Property | Action |
|---|---|
| `shortcut.create-session` | Open a new session |
| `shortcut.next-session` | Switch to the next session |
| `shortcut.previous-session` | Switch to the previous session |
| `shortcut.rename-session` | Rename the current session |

```properties
shortcut.create-session = ctrl + t
shortcut.next-session = ctrl + 2
shortcut.previous-session = ctrl + 1
shortcut.rename-session = ctrl + n
```

To turn off all hardware shortcuts, set `disable-hardware-keyboard-shortcuts = true`.

### 6.5 Other useful properties

| Property | Values | Default | Effect |
|---|---|---|---|
| `default-working-directory` | absolute path | `~` (`$HOME`) | Directory new sessions start in |
| `delete-tmpdir-files-older-than-x-days-on-exit` | `-1`, `0`, or days | `3` | Clean old files from `$TMPDIR` on exit (`-1` = never, `0` = all) |
| `disable-terminal-session-change-toast` | `true`/`false` | `false` | Suppress the toast shown when switching sessions |
| `run-termux-am-socket-server` | `true`/`false` | `true` | Run the local `am` socket server at startup |

### 6.6 Changing colors and fonts

Colors and fonts are not set in `termux.properties`. They are controlled by:

- The **Termux:Styling** plugin (recommended) — install it, then long-press the terminal → **Style** to pick from bundled color schemes and fonts.
- Manually placing `~/.termux/colors.properties` and `~/.termux/font.ttf` files (see the [Terminal Settings wiki](https://wiki.termux.com/wiki/Terminal_Settings)).

---

## 7. The Termux Plugin Apps

Termux's capabilities are extended by separate, optional plugin apps. Each is its own APK and **must be installed from the same source and signature as the main app**.

| Plugin | Adds |
|---|---|
| **Termux:API** | Terminal commands that reach Android features — clipboard, battery status, SMS, location, notifications, camera, sensors, and more. Also requires the `termux-api` package: `pkg install termux-api`. |
| **Termux:Boot** | Runs scripts automatically when the device boots. |
| **Termux:Float** | Runs a Termux terminal in a floating, always-on-top window. |
| **Termux:Styling** | Color schemes and fonts for the terminal. |
| **Termux:Tasker** | A Tasker plugin to run Termux scripts from Tasker automation. |
| **Termux:Widget** | Home-screen widget and launcher shortcuts to run scripts with one tap. |

> [!IMPORTANT]
> Plugins do **not** execute commands themselves — they send execution requests to the Termux app, which runs them. This is why both the plugin and the main app have their own settings (such as log level) that may need configuring.

---

## 8. Sharing Files With Other Apps

Termux registers as both a file *receiver* and a file *viewer*, so it appears in Android's **Share** and **Open with** menus.

- **Send a file to Termux** — from any app, choose **Share** and pick Termux. The file is delivered into Termux for you to save.
- **Open a file with Termux** — choose **Open with → Termux** for supported types.
- **Browse Termux files from other apps** — Termux exposes a documents provider, so its files appear in the Android file picker / Files app under Termux.

You can disable these integrations in `termux.properties`:

| Property | Effect |
|---|---|
| `disable-file-share-receiver = true` | Remove Termux from the **Share** menu |
| `disable-file-view-receiver = true` | Remove Termux from the **Open with** menu |

---

## 9. Running Termux Commands From Other Apps (Automation)

Other apps and automation tools (such as Tasker) can ask Termux to run a command by sending it a `RUN_COMMAND` intent. This is the foundation for automating Termux.

### 9.1 Enable it first

For security, this is **off by default**. You must opt in:

1. Set the property:

   ```properties
   allow-external-apps = true
   ```

   in `~/.termux/termux.properties`, then reload properties.

2. The calling app must hold the `com.termux.permission.RUN_COMMAND` permission.

> [!CAUTION]
> Enabling `allow-external-apps` lets other installed apps run commands in your Termux environment. Only enable it if you understand the risk, and only grant the `RUN_COMMAND` permission to apps you trust. If an external app attempts a command while the policy is disabled, Termux shows a notification so you know an app tried.

### 9.2 The RUN_COMMAND intent

Send an explicit intent to the service `com.termux/com.termux.app.RunCommandService` with action `com.termux.RUN_COMMAND`. Key extras:

| Extra (string name) | Type | Purpose |
|---|---|---|
| `com.termux.RUN_COMMAND_PATH` | String | **Required.** Absolute path to the executable (e.g. `/data/data/com.termux/files/usr/bin/top`) |
| `com.termux.RUN_COMMAND_ARGUMENTS` | String[] | Arguments to the executable |
| `com.termux.RUN_COMMAND_WORKDIR` | String | Working directory |
| `com.termux.RUN_COMMAND_BACKGROUND` | boolean | `true` runs in the background (no terminal session); `false` (default) runs in a visible session |
| `com.termux.RUN_COMMAND_RUNNER` | String | Explicit runner: `terminal-session` or `app-shell` (overrides `BACKGROUND`) |
| `com.termux.RUN_COMMAND_SESSION_ACTION` | String | What to do with the session/activity for foreground commands |
| `com.termux.RUN_COMMAND_STDIN` | String | Standard input to feed the command |
| `com.termux.RUN_COMMAND_COMMAND_LABEL` | String | A human-readable label for the command |

Example using Android's `am` tool (from another Termux session, or adb):

```bash
am startservice --user 0 \
  -n com.termux/com.termux.app.RunCommandService \
  -a com.termux.RUN_COMMAND \
  --es com.termux.RUN_COMMAND_PATH '/data/data/com.termux/files/usr/bin/top' \
  --esa com.termux.RUN_COMMAND_ARGUMENTS '-n,2' \
  --es com.termux.RUN_COMMAND_WORKDIR '/data/data/com.termux/files/home' \
  --ez com.termux.RUN_COMMAND_BACKGROUND 'false'
```

```text
Starting service: Intent { act=com.termux.RUN_COMMAND ... }
```

> [!NOTE]
> The executable path must be a regular, readable, executable file. Commas inside arguments need special handling when sent via `am` (Termux supports a comma-alternative replacement extra). Full, authoritative details — including result-file extras and pending-intent results — are on the [RUN_COMMAND Intent wiki page](https://github.com/termux/termux-app/wiki/RUN_COMMAND-Intent).

---

## 10. Settings and Debugging

Open settings via the drawer's **settings** button or the context menu's **Settings** item. Settings are grouped per app (Termux, and each installed plugin) and include a **Debugging** section.

### Setting the log level

For bug reports, raise the log level under **Settings → Termux → Debugging → Log Level**:

- `Off` — log nothing.
- `Normal` — errors, warnings, info, and stack traces *(default)*.
- `Debug` — adds debug messages.
- `Verbose` — adds verbose messages.

> [!WARNING]
> Set the level back to **Normal** when you are done. Verbose logging is slower and may write private data to `logcat`. When reporting a problem with a plugin, set the log level for **both** the plugin and the main Termux app.

### Generating a report

Long-press the terminal → **More → Report Issue** to generate a debug report (optionally including file `stat` info and a `logcat` dump). Post the **complete text** of the report when filing issues — issues opened with only screenshots of an error are typically closed automatically.

---

## 11. Troubleshooting

### Error: `[Process completed (signal 9) - press Enter]`

**Cause** — On Android 12+, the OS kills background ("phantom") processes once more than 32 exist across all apps, and kills processes using excessive CPU. Your shell or a child process was terminated by the system, not by you.

**Solution** — Disable phantom-process trimming. On many devices this can be done with ADB / Developer Options; see the [TLDR comment on issue #2366](https://github.com/termux/termux-app/issues/2366#issuecomment-1237468220) and the [phantom processes documentation](https://github.com/agnostic-apollo/Android-Docs/blob/master/en/docs/apps/processes/phantom-cached-and-empty-processes.md).

**Prevention** — Keep long-running work in the foreground session, disable battery optimization for Termux, and acquire a wake-lock (context menu → **Keep screen on**, or run `termux-wake-lock`).

### Error: App freezes or is killed in the background

**Cause** — Aggressive battery/background management by the OS or vendor skin (Samsung One UI, MIUI, etc.).

**Solution** — Disable battery optimization for Termux in Android settings. See [dontkillmyapp.com](https://dontkillmyapp.com/) for device-specific steps.

**Prevention** — Use a wake-lock for long jobs; avoid backgrounding Termux during important tasks.

### Error: `App not installed` / `signatures do not match previously installed version`

**Cause** — You are mixing Termux APKs from different sources, which are signed with different keys.

**Solution** — Uninstall **all** Termux and plugin APKs, then reinstall everything from a single source.

**Prevention** — Always install the app and every plugin from the same source.

### Error: Terminal crashes when pasting text

**Cause** — Pasting raw control characters (such as a literal ESC, Unicode 27) can crash the emulator ([#5119](https://github.com/termux/termux-app/issues/5119)).

**Solution** — Avoid pasting binary or control-laden content directly. Save it to a file and read it with a program instead.

### Error: `repository is under maintenance or down` from `apt` / `pkg`

**Cause** — The package mirror you are using is temporarily unavailable.

**Solution** — Switch mirrors with `termux-change-repo`, or follow the [Package Management guide](https://github.com/termux/termux-packages/wiki/Package-Management).

### Error: Bootstrap installation fails on first launch

**Cause** — Termux must run as the **primary user** and from internal storage. Installing on a secondary user, work profile, or portable SD card breaks the required file paths.

**Solution** — Uninstall, switch to the primary user, ensure Termux is on internal storage, and reinstall. The error dialog offers **Try again**, which wipes the partial install and retries.

### Issue: My letters don't appear until I press Enter (some Samsung devices)

**Cause** — A keyboard/IME quirk on certain devices.

**Solution** — Set `enforce-char-based-input = true` in `termux.properties` and reload.

### Issue: `Ctrl+Space` does nothing

**Cause** — Some ROMs swallow the `Ctrl+Space` combination.

**Solution** — Set `ctrl-space-workaround = true` in `termux.properties` and reload.

### Issue: The extra-keys toolbar is missing

**Cause** — The toolbar was toggled off.

**Solution** — Long-press the **keyboard-toggle** button in the drawer to bring the toolbar back, or check your `extra-keys` property is valid.

---

## 12. Frequently Asked Questions

**Q: Do I need to root my device to use Termux?**
No. Termux runs entirely within its own private application directory and requires no root or special setup.

**Q: Where are my files stored?**
Your home directory is `/data/data/com.termux/files/home` (referred to as `~` or `$HOME`). Installed programs live under `/data/data/com.termux/files/usr` (`$PREFIX`). To reach your photos and downloads, run `termux-setup-storage` to create `~/storage`.

**Q: Why is this app separate from the packages like Python and Git?**
This repository is the Termux *app* — the terminal UI and emulator. The thousands of installable programs are built and maintained in [termux-packages](https://github.com/termux/termux-packages) and installed at runtime with `pkg`.

**Q: Which Android versions are supported?**
Android 7.0+ for full app and package support. Android 5/6 can run the app (GitHub `apt-android-5` builds) but cannot update packages.

**Q: Should I install from the Play Store?**
For most users, no. The Play Store build is experimental with missing features. Prefer F-Droid or GitHub.

**Q: How do I keep a long-running task alive in the background?**
Acquire a wake-lock (context menu → **Keep screen on**, or `termux-wake-lock`), disable battery optimization for Termux, and on Android 12+ disable phantom-process killing.

**Q: How do I change the color scheme and font?**
Install the **Termux:Styling** plugin and pick from the context menu's **Style** option, or place `colors.properties` and `font.ttf` in `~/.termux/`.

**Q: How do I run a Termux command automatically at boot?**
Install the **Termux:Boot** plugin and place a script in `~/.termux/boot/`.

**Q: Can another app run commands in Termux?**
Yes, via the `RUN_COMMAND` intent, but only after you set `allow-external-apps = true` and grant the app the `com.termux.permission.RUN_COMMAND` permission. See [Automation](#9-running-termux-commands-from-other-apps-automation).

**Q: I changed `termux.properties` but nothing happened.**
Reload properties: long-press the terminal → **More → Style**, or reopen the app. Also confirm you edited the file Termux actually reads (`~/.termux/termux.properties` takes priority over `~/.config/termux/termux.properties`).

**Q: How do I get more help?**
Long-press the terminal and choose **Help** to open the Termux Wiki, or visit the [community links](https://wiki.termux.com/wiki/Community) (Reddit, Matrix/Gitter, and the support email).

**Q: How do I report a bug?**
Use the context menu's **Report Issue** to generate a complete text report, then file it on the [issue tracker](https://github.com/termux/termux-app/issues). Always paste the full report text, not a screenshot.

**Q: What is a "failsafe" session?**
A minimal shell that skips your startup scripts — use it to recover from a broken `~/.bashrc` or similar. Long-press **NEW SESSION** to start one.

---

_Generated June 2026 from termux/termux-app at 30ebb2d. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._