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 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.

1. Quick Start

1. Install the Termux APK from a single trusted source (see 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:

   ~ $
   

4. Update the package lists and install something useful:

   pkg upgrade
   pkg install git python openssh
   

5. Try it out:

   python --version
   

   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.

2. Requirements

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.

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 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 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), and manually pull-to-refresh the Updates tab.

3.2 GitHub

Get APKs from GitHub Releases (version >= 0.118.0) or from the Build action artifacts 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. 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 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 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:

┌─────────────────────────────────────┐
│                                     │  ← 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.

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.

5.3 The terminal context menu

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

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.)

5.5 Installing software with pkg

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

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:

pkg install git python nodejs openssh nano

Reading package lists... Done
...

Note

If apt/pkg reports repository is under maintenance or down, follow the Package Management guide. 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:

termux-setup-storage

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

ls ~/storage/downloads

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:

mkdir -p ~/.termux && nano ~/.termux/termux.properties

6.1 Common terminal settings

Example termux.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:

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

A simpler single row:

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:

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

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:

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

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).

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.

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:

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:

   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:

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

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'

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.

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 and the phantom processes documentation.

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 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).

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.

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 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.

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 (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. 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.