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

% TERMUX(1) As of application version 0.117 | Termux User Documentation
% The Termux project contributors
% September 25, 2021

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.
 - Opening URL selector.
 - Sharing text from the terminal to other apps (e.g. email or SMS).
 - Launching password autofill service.
 - Resetting the terminal if it gets stuck.
 - Force terminating the current session.
 - Styling the terminal by selecting a font and a color scheme.
 - Check box for toggling screen always on feature.
 - Showing this help page.
 - Opening settings menu.
 - Reporting issue.

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

 - Button for opening Termux settings.
 - 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+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:

    - **back** - The default. A standard behaviour 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 behaviour 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 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:

    - **arrows-only** - use symbols only for arrow buttons.
    - **arrows-all**  - replace some labels with well-known symbols.
    - **all**         - use symbols instead labels where possible.
    - **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:

    - **enable/disable** - whether to enable or disable soft keyboard
      at all.
    - **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:

    - **block**
    - **bar**
    - **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:

    - **virtual** - volume buttons will act as special keys.
    - **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.

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

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

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

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