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

% 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:

    `@TERMUX_HOME@`
    :    A home directory where user can place his files.

    `@TERMUX_PREFIX@`
    :    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 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 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 @TERMUX_PREFIX@

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

        @TERMUX_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

        @TERMUX_PREFIX@

    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:

        @TERMUX_PREFIX@/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.