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:

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

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