TERMUX(1) Termux User Documentation TERMUX(1)
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:
o Data processing with Python.
o Programming in a development environment.
o Downloading and managing files and pages using time-established
tools.
o Learning the basics of the Linux command line environment.
o Running an SSH client.
o 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:
o Selecting and pasting text.
o Opening URL selector.
o Sharing text from the terminal to other apps (e.g. email or SMS).
o Launching password autofill service.
o Resetting the terminal if it gets stuck.
o Force terminating the current session.
o Styling the terminal by selecting a font and a color scheme.
o Check box for toggling screen always on feature.
o Showing this help page.
o Opening settings menu.
o Reporting issue.
The navigation drawer is revealed by swiping inwards from the left part
of the screen. It has four elements:
o Button for opening Termux settings.
o A list of sessions. Clicking on a session shows it in the terminal
while long pressing allows you to specify a session title.
o A button to toggle visibility of the touch keyboard.
o 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:
o Exiting all running terminal sessions.
o Use a wake lock to avoid entering sleep mode.
o 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+K
Toggle soft keyboard.
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.
allow-external-apps
If set to "true", external applications are allowed to execute
arbitrary commands within the Termux environment through the
RUN_COMMAND intent, if permission
com.termux.permission.RUN_COMMAND has been granted.
This option is also required for functionality of termux-open
and other things using Content Provider as of Termux v0.118+.
back-key
Controls the behaviour of key "back".
Accepts a one of these values:
o back - The default. A standard behaviour of Android OS, will
hide touch keyboard if shown, if not - move to home screen
without closing application.
o escape - When set, touching the key will send escape
character.
bell-character
Controls the behaviour of bell characters.
Accepts a one of these values:
o vibrate - vibrate the device.
o beep - short sound beep.
o ignore - ignore bell characters.
If property is not being set, the default behaviour is
equivalent to "bell-character=vibrate".
ctrl-space-workaround
Set this to "true" if ctrl+space key combination does not work
on hardware keyboard.
default-working-directory
An absolute path to default working directory. Default is
Termux home.
disable-hardware-keyboard-shortcuts
Set this to "true" to disable hardware keyboard shortcuts.
disable-terminal-session-change-toast
Set this to "true" to disable toast notifications on terminal
session changes.
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.
This option is disabled by default as cause some issues with
correctly working keyboards.
extra-keys-style
Controls the style of extra keys row view.
Accepts a one of these values:
o arrows-only - use symbols only for arrow buttons.
o arrows-all - replace some labels with well-known symbols.
o all - use symbols instead labels where possible.
o none - don't replace labels with symbols at all.
If extra keys row symbols are not displayed properly, use
"none".
extra-keys-text-all-caps
Set this to "true" to force capitalize the text on extra keys
row buttons.
fullscreen
Set this to "true" to have Termux running in a full screen mode.
The full screen mode may not work correctly on some devices.
This issue can be fixed by enabling "use-fullscreen-workaround".
hide-soft-keyboard-on-startup
Set this to "true" to make software keyboard hidden on
application startup.
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.
soft-keyboard-toggle-behaviour
Controls the behaviour of "keyboard" button located in the
drawer.
Accepts a one of these values:
o enable/disable - whether to enable or disable soft keyboard at
all.
o show/hide - whether to show or hide soft keyboard.
Default is show/hide.
terminal-cursor-blink-rate
Controls the cursor blink rate. Valid value range is from 100
to 2000. If set to 0, the cursor blinking will be disabled.
terminal-cursor-style
Controls the style of terminal cursor.
Accepts a one of these values:
o block
o bar
o underline
Default is block.
terminal-margin-horizontal
Controls the terminal margin on left and right. Value is
defined in dp units in range from 0 to 100. Default is 3.
terminal-margin-vertical
Controls the terminal margin on top and bottom. Value is
defined in dp units in range from 0 to 100. Default is 0.
terminal-onclick-url-open
If set to "true", clicking on URL link in terminal transcript
will open it.
terminal-toolbar-height
Controls the terminal toolbar height. Valid value range is from
0.4 to 3.0. Default is 1.
terminal-transcript-rows
Controls how much lines are stored in scrollback buffer. Valid
value range is from 100 to 50000. Default is 2000.
Note that setting high values may affect console rendering
performance.
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.
use-fullscreen-workaround
Set this to "true" if experience issues with full screen mode.
volume-keys
Controls the behaviour of volume buttons.
Accepts a one of these values:
o virtual - volume buttons will act as special keys.
o volume - control sound volume as usual.
Default is "virtual".
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.
o CTRL ("special key")
o ALT ("special key")
o FN ("special key")
o SPACE
o ESC
o TAB
o HOME
o END
o PGUP
o PGDN
o INS
o DEL
o BKSP
o UP
o LEFT
o RIGHT
o DOWN
o ENTER
o BACKSLASH
o QUOTE
o APOSTROPHE
o F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12
o KEYBOARD (hide the keyboard)
o 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 behaviour 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(1) 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 single-user only. It operates under user
id assigned by Android OS which you cannot change.
There no privilege separation, all Termux files such as package
data or user data in home directory is owned by same user id.
Be extremely careful when executing third-party scripts as they
can easily do unauthorized modifications which may lead to
broken Termux installation or lost user data.
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 may
become 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.
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.
BACKUP AND RESTORE
Termux installation can be backed up by archiving directory $PREFIX and
storing the file in safe location. A rudimentary backup tools are
already bundled with package `termux-tools', though you are free to use
your own.
How to back up Termux installation ($PREFIX):
termux-backup /sdcard/termux.tar.gz
How to restore Termux installation from backup:
termux-restore /sdcard/termux.tar.gz
Note that backup performed this way does not include the content of
your home directory. Restoring procedure will overwrite the content of
$PREFIX deleting all extra files which were not present in backup
archive. So be careful!
RECOVERY IF SESSION FAILS TO START
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.
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>.
AUTHORS
The Termux project contributors.
As of application version 0.117
September 25, 2021 TERMUX(1)
