termux-packages/packages/termux-tools/termux.1.md

% TERMUX(1) As of application version 0.101 | Termux User Documentation % By @xeffyr (Leonid Pliushch leonid.pliushch@gmail.com) and Termux Wiki contributors. % October 2, 2020

NAME

Termux - a terminal emulator application for Android OS.

DESCRIPTION

Termux is an Android terminal emulator and Linux environment application that works directly with no rooting or setup required. A minimal base system is installed automatically, additional packages are available using the package manager.

Here is a just a brief list of things you can do with Termux:

• Data processing with Python.
• Programming in a development environment.
• Downloading and managing files and pages using time-established tools.
• Learning the basics of the Linux command line environment.
• Running an SSH client.
• Synchronizing and backing up your files.

Of course, usage is not limited to the topics listed above.

Note that it is expected that you have at least basic knowledge about command line and shell scripting.

USER INTERFACE

At launch Termux shows a terminal interface, whose text size can be adjusted by pinch zooming or double tapping and pulling the content towards or from you.

Besides the terminal there are three additional interface elements available: a context menu, navigation drawer and notification.

The context menu can be shown by long pressing anywhere on the terminal. It provides menu entries for:

• Selecting and pasting text.
• Sharing text from the terminal to other apps (e.g. email or SMS)
• Resetting the terminal if it gets stuck.
• Hangup (exiting the current terminal session).
• Styling the terminal by selecting a font and a color scheme.
• Showing this help page.

The navigation drawer is revealed by swiping inwards from the left part of the screen. It has three elements:

• A list of sessions. Clicking on a session shows it in the terminal while long pressing allows you to specify a session title.
• A button to toggle visibility of the touch keyboard.
• A button to create new terminal sessions. Long press it for creating a named session or a fail-safe one.

The notification, available when a terminal session is running, is available by pulling down the notification menu. Pressing the notification leads to the most current terminal session. It may also be expanded by pinch-zooming or performing a single-finger glide to expose these actions:

• Exiting all running terminal sessions.
• Use a wake lock to avoid entering sleep mode.
• Use a high performance wifi lock to maximize wifi performance.

With a wake lock held the notification and Termux background processes will be available even if no terminal session is running, which allows server and other background processes to run more reliably.

Using wake-lock

If you are executing a long operation in Termux and want to turn off device screen, you need to enable Wake Lock. You can do that through the notification, by clicking on button "Acquire wakelock" or by executing this command:

termux-wake-lock

Wake locks are needed to prevent device from going into sleep mode. If you will not do that, your tasks will run very slowly or even be paused. Acquired Wake Lock implies a higher battery usage during standby.

Please note that Wake Lock does not affect network performance when screen is off and you may observe a packet loss.

To release Wake Lock, you need to either run command

termux-wake-unlock

or click button "Release wakelock" in notification.

TOUCH KEYBOARD

Use of keys like ALT, CTRL, ESC is necessary for working with a command line programs. As Android touch keyboards usually do not include such keys, Termux uses the Volume-Down button to emulate the CTRL key. For example, holding the Volume-Down and "L" on touch keyboard will send the same input as pressing key combination CTRL+L on a hardware keyboard.

The result of using CTRL (Volume-Down) in combination with a key depends on which program is being used. See below for the list of common shortcuts usable in most shells.

CTRL+A

Move cursor to the beginning of line

CTRL+C

Abort current process by sending SIGINT

CTRL+D

Logout of a terminal session by sending EOF

CTRL+E

Move cursor to the end of line

CTRL+K

Delete from cursor to the end of line

CTRL+U

Delete from cursor to the beginning of line

CTRL+L

Clear the terminal

CTRL+Z

Suspend current process by sending SIGTSTP

CTRL+W

Clear prompt before word

The Volume-Up key also serves as a special key to produce certain input. But please note that Volume-Up is not equivalent of the ALT key.

Volume-Up+E

Escape key

Volume-Up+T

Tab key

Volume-Up+1

F1, Volume-Up+2 will produce F2, etc

Volume-Up+0

F10 key

Volume-Up+B

ALT+B, back a word when using Readline

Volume-Up+F

ALT+F, forward a word when using Realine

Volume-Up+X

ALT+X

Volume-Up+W

Up arrow key

Volume-Up+A

Left arrow key

Volume-Up+S

Down arrow key

Volume-Up+D

Right arrow key

Volume-Up+L

|, the pipe character

Volume-Up+H

~, the tilde character

Volume-Up+U

_, the underscore character

Volume-Up+P

Page Up key

Volume-Up+N

Page Down key

Volume-Up+.

CTRL+\, send SIGQUIT

Volume-Up+V

Show the volume control

Volume-Up+Q

Toggle extra keys row

Volume-Up+K

Another variant to toggle extra keys row

Termux supports the special key row which allows you to specify desired keys like CTRL or ESC or their combinations. See section EXTRA KEYS ROW.

HARDWARE KEYBOARD

The following shortcuts are available when using Termux with a hardware (e.g. Bluetooth) keyboard:

CTRL+ALT+C

Create new session

CTRL+ALT+R

Rename current session

CTRL+ALT+<DOWN>

Switch to next session

CTRL+ALT+<UP>

Switch to previous session

CTRL+ALT+<RIGHT>

Open drawer

CTRL+ALT+<LEFT>

Close drawer

CTRL+ALT+M

Show menu

CTRL+ALT+U

Select URL

CTRL+ALT+V

Paste clipboard content

CTRL+ALT+ (+/-)

Adjust font size

CTRL+ALT+ (1-9)

Go to numbered session

These shortcuts do not work with touch keyboard or extra keys row.

CONFIGURATION

All Termux configuration is done through text file located at

~/.termux/termux.properties

It uses a simple key=value property syntax. See below for all supported properties.

Note that updated configuration takes effect only when you have executed

termux-reload-settings

or have restarted the application.

back-key

Controls the behavior of key "back".

Accepts a one of these values:

• back - The default. A standard behavior of Android OS, will hide touch keyboard if shown, if not - move to home screen without closing application.

• escape - When set, touching the key will send escape character.

bell-character

Controls the behavior of bell characters.

Accepts a one of these values:

• vibrate - vibrate the device.
• beep - short sound beep.
• ignore - ignore bell characters.

If property is not being set, the default behavior is equivalent to "bell-character=vibrate".

enforce-char-based-input

Set this to "true" if you have issues with touch keyboard. For example text is not being sent to terminal until you tap space. Or keyboard shows the wrong layout, for example numeric.

Recommended for people using Samsung devices with stock touch keyboard.

shortcut.create-session

Sets a key combination for creating new session.

For example, use of

shortcut.create-session = ctrl + t

will allow to open a new terminal session by pressing CTRL + t.

shortcut.next-session

Sets a key combination for switching to the next session. Value format is same as for "shortcut.create-session" property.

shortcut.previous-session

Sets a key combination for switching to the previous session. Value format is same as for "shortcut.create-session" property.

shortcut.rename-session

Sets a key combination for opening a dialog for renaming the current session. Value format is same as for "shortcut.create-session" property.

use-black-ui

If set to "true", application will use primarily black color for the most of user interface elements.

Setting this to "false" will have opposite effect.

If the property is not set, then application will choose colors accordingly to the current system theme.

EXTRA KEYS ROW

Termux also has an extra keys row(s) which allows you to extend your current keyboard. To enable the extra keys row you have to long tap on the keyboard button in the left drawer menu or Volume-Down+K key combination.

Layout of the extra keys rows is configurable through the standard Termux configuration file located in

~/.termux/termux.properties

See section CONFIGURATION to learn more about Termux properties.

Sample configuration of 2 extra keys rows:

extra-keys = [ \
  ['ESC','/','-','HOME','UP','END','PGUP'], \
  ['TAB','CTRL','ALT','LEFT','DOWN','RIGHT','PGDN'] \
]

Configuration may be done as one line or be spread between multiple lines by using backslashes like in example above.

Value format is 2-dimensional JSON array.

It is possible to configure a popups buttons which can be triggered by swiping up on the respective keys.

Here is a syntax for the popup key object:

{key: KEY, popup: POPUP_KEY}

Alternate, more advanced syntax for defining the popup:

{key: KEY, popup: {macro: 'KEY COMBINATION', display: 'Key combo'}}

An example of complex Termux extra keys configuration with using popups:

extra-keys = [[ \
  {key: ESC, popup: {macro: "CTRL f d", display: "tmux exit"}}, \
  {key: CTRL, popup: {macro: "CTRL f BKSP", display: "tmux ←"}}, \
  {key: ALT, popup: {macro: "CTRL f TAB", display: "tmux →"}}, \
  {key: TAB, popup: {macro: "ALT a", display: A-a}}, \
  {key: LEFT, popup: HOME}, \
  {key: DOWN, popup: PGDN}, \
  {key: UP, popup: PGUP}, \
  {key: RIGHT, popup: END}, \
  {macro: "ALT j", display: A-j, popup: {macro: "ALT g", display: A-g}}, \
  {key: KEYBOARD, popup: {macro: "CTRL d", display: exit}} \
]]

SUPPORTED KEYS

Each key "entry" can be either a string such as '|', '/', '=' or one of the values listed below.

• CTRL ("special key")
• ALT ("special key")
• FN ("special key")
• SPACE
• ESC
• TAB
• HOME
• END
• PGUP
• PGDN
• INS
• DEL
• BKSP
• UP
• LEFT
• RIGHT
• DOWN
• ENTER
• BACKSLASH
• QUOTE
• APOSTROPHE
• F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12
• KEYBOARD (hide the keyboard)
• DRAWER (open app drawer)

Each of the three "special keys" listed above should only be listed at most ONCE in the extra-keys definition i.e. do NOT have more than one CTRL key. Having more than one instance of any "special key" will result in a bug whereby those keys do not function correctly.

A note about backslash: this character has special meaning and you should not use it directly to define a key. Use 'BACKSLASH' instead, otherwise properly escape it - '\\\\'.

TEXT INPUT VIEW

Termux does not support the advanced features of touch keyboards like autocorrection, prediction and swipe typing. To solve this, it provides a text input view. Text entered in it will get pasted to the terminal. Because it is a native Android text input view, all touch keyboard features will work. To access the text input view you have to swipe the extra keys row to the left.

DIFFERENCES FROM LINUX DISTRIBUTIONS

Termux does not guarantee full compatibility with GNU/Linux environment and you may observe inconvenient behavior of some utilities, especially from those which were not officially ported to Android OS (Termux). See below to learn about the major differences.

No compliance with Filesystem Hierarchy Standard

Termux does not follow Filesystem Hierarchy Standard because Android does not make root file system world-writable and Termux is not a virtual machine.

All files are stored within the application private directory on internal storage to ensure that application has full control over its files and also special features like symlinks or file access modes (chmod(1)).

The data is being stored in 2 main locations:

/data/data/com.termux/files/home

A home directory where user can place his files.

/data/data/com.termux/files/usr

The prefix - a place where all packages are being extracted during installation. Has a directory structure similar to the root file system of traditional Linux distributions.

You may have problems with running some utilities accessing standard directories like /var or /tmp.

Termux has some workarounds for that. For example, it preloads a shared library "libtermux-exec.so" which intercepts "execve()" and maps /bin to directory located in the prefix.

With utility "termux-chroot" that comes as part of package "proot" you should be able to emulate a FHS-compliant root file system.

No GNU libc

Termux does not use GNU libc. Instead it uses a Bionic libc and dynamic linker provided by Android OS.

Programs linked with GNU libc will not work in Termux. Bionic libc has different ABI and dynamic linker path. You likely will observe weird messages "No such file or directory" when attempting to run executable file but know that file is present. That happens because dynamic linker cannot be started because does not exist on expected location.

Programs which were statically-linked with GNU libc may misbehave too. You may get a "Bad system call" errors. Also networking software will likely show DNS resolution errors because Android does not provide /etc/resolv.conf and by default even in statically-linked programs GNU libc still uses libresolv as shared library which is not present.

Consider to rebuild your software in Termux environment by using clang.

Only one user

Termux environment is sinle-user only. There any kind of privilege separation and you cannot change the given user id or name.

Be extremely careful when executing third-party scripts as they are able to tamper files in Termux prefix.

PACKAGE MANAGEMENT

Termux uses apt(8) as package manager, just like Debian. However we highly recommend to use our wrapper pkg which simplifies certain tasks and also automatically picks the mirror to help reduce traffic usage on the origin repositories. See its usage below.

Installing package:

pkg install <package name>

Uninstall package:

pkg uninstall <package name>

Reinstall package:

pkg reinstall <package name>

List the all available packages:

pkg list-all

List the installed packages:

pkg list-installed

Search packages:

pkg search <query>

Upgrade packages:

pkg upgrade

Termux implements a rolling-release updates scheme to reduce amount of work needed to maintain packages since developer team is small. You need to check for updates on a regular basis, especially before installing a new package. Otherwise at some day your environment will be broken.

If you prefer to use apt(8) over pkg, please ensure that for installing updates you use these commands:

apt update
apt full-upgrade

Also always run "apt update" before installing package. The wrapper pkg does that for you automatically.

RECOVERY

If Termux session cannot be launched due to misconfiguration in dotfiles, you still should be able to start a failsafe session. How-to:

1. Long click on Termux launcher icon.
2. Select shortcut "failsafe".

Once you are in a failsafe session, navigate to Termux home directory and rename or delete the dotfiles causing the issue. Finally, restart the application.

If problem is not with the dotfiles, for example you have messed up Termux prefix and do not know what to do, our recommendation is complete reinstallation by executing

rm -rf /data/data/com.termux/files/usr

This will erase all packages but will not touch your home directory.

ACCESSING THE STORAGE

By default Termux does not provide access to storage volumes where you typically store your files like pictures or documents. In order to get access to shared storage, execute the next command:

termux-setup-storage

This will prompt you for Storage Access Permission. Once it granted, Termux will setup symlinks to various standard directories under "~/storage".

~/storage/shared

The root directory of shared storage.

~/storage/downloads

Standard directory where downloaded files are stored.

~/storage/dcim

Standard directory where captured photos and video are stored.

~/storage/pictures

Standard directory for photo gallery.

~/storage/music

Standard directory where music albums are stored.

~/storage/movies

Standard directory where videos are stored.

~/storage/external-1

The private directory of Termux on external SD-card.

Note that if you decide to wipe Termux data or uninstall application, all files stored in private application directories will be deleted.

Note about external storage

Android does not allow to have a direct write access to external storage like SD-cards and USB drives unless you are not doing so in private directories like

/storage/0123-ABCD/Android/data/com.termux/files

If you want to write files to storage root or directory other than private one of Termux, you need superuser permissions.

Android applications like file managers can do that because they use a special API called Storage Access Framework. But command line utilities cannot use this one.

Transferring files to Termux

To put files into Termux, you have 2 variants.

The first one would be copying or moving files from shared storage into Termux directory by using cp(1) or mv(1). You may also setup a some file server and access it through localhost.

The second variant would be usage of file manager application which supports Storage Access Framework and is able to attach volumes. Just select "Termux" volume from menu and you should be able to access home directory.

Sharing data to other applications

You may give a temporary read access to certain files stored within Termux. Use command

termux-open

to do this. You may specify a MIME type by using option "--content-type" when sharing the file to ensure that it will be opened by correct application.

Similarly to sharing files, you may share URL. You will need to use command "termux-open-url".

Android 11+

Since Android 11 Termux may not be able to provide the access to shared and external storage. This is not a bug. Just new restrictions which enforce storage access over Android API which cannot be used by shell.

From that point you are locked to Termux private directories like $HOME or such on storage volume:

/storage/self/primary/Android/data/com.termux/files

You still should be able to exchange files with Termux home directory by accessing Termux virtual volume through File managers supporting Storage Access Framework.

ENVIRONMENT

Termux exposes some variables set by Android OS as well as its own. Here is a brief list of default environment variables, their description and values.

HOME

Path to Termux home.

Termux home directory is a place for user files. It is located at

/data/data/com.termux/files/home

Do not modify the value of this environment variable since Termux doesn't support customizing location of the home directory.

PREFIX

Termux installation prefix.

A base directory for Termux installation. It is located at

/data/data/com.termux/files/usr

Do not modify the value of this environment variable. Termux packages are not relocatable. Some of them may also look this variable to find their files.

PATH

Utility lookup paths for shells.

Used by shells to find command line utilities. By default, it contains this value:

/data/data/com.termux/files/usr/bin

You may append or prepend your own paths if needed, for example:

export PATH=$PATH:$HOME/bin

But make sure that Termux-specific bin directory location is not missing.

LANG

Locale.

Mimic support of UTF-8 en_US locale, so programs will properly handle Unicode characters.

Default value is "en_US.UTF-8".

As Termux does not support locales, changing this variable is not recommended and may have unexpected effects.

FILES

A list of files which have special meaning for the Termux application.

~/bin/termux-url-opener

A script for processing an intent when a third-party application shares an URL with Termux.

~/bin/termux-file-editor

A script for processing an intent when a third-party application shares a file with Termux.

~/storage

A directory containing symlinks to shared or external storages and to certain standard directories.

Do not store files directly under this directory. Put them to locations accessible through symlinks instead.

~/.termux/termux.properties

Application configuration file.

~/.termux/colors.properties

A configuration file containing a color scheme for styling the terminal. Usually is generated by Termux:Styling add-on.

~/.termux/font.ttf

A file containing TTF font data for styling the terminal. Usually is generated by Termux:Styling add-on.

BUGS

Report application issues to https://github.com/termux/termux-app/issues.

Package-related issues should be reported to https://github.com/termux/termux-packages/issues.

SEE ALSO

Complete and up-to-date infomation about Termux usage is available on Termux Wiki here: https://wiki.termux.com/wiki/Main_Page.