Termuxis an Android terminal application and Linux environment.
Note that this repository is for the app itself (the user interface and the terminal emulation). For the packages installable inside the app, seetermux/termux-packages.
Quick how-to about Termux package management is available atPackage Management.It also has info on how to fixrepository is under maintenance or down
errors when runningapt
orpkg
commands.
We are looking for Termux Android application maintainers.
NOTICE: Termux may be unstable on Android 12+.Android OS will kill any (phantom) processes greater than 32 (limit is for all apps combined) and also kill any processes using excessive CPU. You may get[Process completed (signal 9) - press Enter]
message in the terminal without actually exiting the shell process yourself. Check the related issue#2366,issue tracker,phantom cached and empty processes docsandthis TLDR commenton how to disable trimming of phantom and excessive cpu usage processes. A proper docs page will be added later. An option to disable the killing should be available in Android 12L or 13, so upgrade at your own risk if you are on Android 11, specially if you are not rooted.
- Termux App and Plugins
- Installation
- Uninstallation
- Important Links
- Debugging
- For Maintainers and Contributors
- Forking
The coreTermuxapp comes with the following optional plugin apps.
Latest version isv0.118.1
.
NOTICE: It is highly recommended that you update tov0.118.0
or higher ASAP for various bug fixes, including a critical world-readable vulnerability reportedhere.Seebelowfor information regarding Termux on Google Play.
Termux can be obtained through various sources listed below foronlyAndroid>= 7
with full support for apps and packages.
Support for both app and packages was dropped for Android5
and6
on2020-01-01atv0.83
,however it was re-added just for the appwithout any support for package updateson2022-05-24via theGitHubsources. Checkherefor the details.
The APK files of different sources are signed with different signature keys. TheTermux
app and all its plugins use the samesharedUserId
com.termux
and so all their APKs installed on a device must have been signed with the same signature key to work together and so they must all be installed from the same source. Do not attempt to mix them together, i.e do not try to install an app or plugin fromF-Droid
and another one from a different source likeGitHub
.Android Package Manager will also normally not allow installation of APKs with different signatures and you will get errors on installation likeApp not installed
,Failed to install due to an unknown error
,INSTALL_FAILED_UPDATE_INCOMPATIBLE
,INSTALL_FAILED_SHARED_USER_INCOMPATIBLE
,signatures do not match previously installed version
,etc. This restriction can be bypassed with root or with custom roms.
If you wish to install from a different source, then you mustuninstall any and all existing Termux or its plugin app APKsfrom your device first, then install all new APKs from the same new source. CheckUninstallationsection for details. You may also want to considerBacking up Termuxbefore the uninstallation so that you can restore it after re-installing from Termux different source.
In the following paragraphs,"bootstrap"refers to the minimal packages that are shipped with thetermux-app
itself to start a working shell environment. Its zips are built and releasedhere.
Termux application can be obtained fromF-Droid
fromhere.
Youdo notneed to download theF-Droid
app (via theDownload F-Droid
link) to install Termux. You can download the Termux APK directly from the site by clicking theDownload APK
link at the bottom of each version section.
It usually takes a few days (or even a week or more) for updates to be available onF-Droid
once an update has been released onGitHub
.TheF-Droid
releases are built and published byF-Droid
once theydetecta newGitHub
release. The Termux maintainersdo nothave any control over the building and publishing of the Termux apps onF-Droid
.Moreover, the Termux maintainers also do not have access to the APK signing keys ofF-Droid
releases, so we cannot release an APK ourselves onGitHub
that would be compatible withF-Droid
releases.
TheF-Droid
app often may not notify you of updates and you will manually have to do a pull down swipe action in theUpdates
tab of the app for it to check updates. Make sure battery optimizations are disabled for the app, checkhttps://dontkillmyapp.com/for details on how to do that.
Only a universal APK is released, which will work on all supported architectures. The APK and bootstrap installation size will be~180MB
.F-Droid
doesnot supportarchitecture specific APKs.
Termux application can be obtained onGitHub
either fromGitHub Releases
for version>= 0.118.0
or fromGitHub Build Action
workflows.For android>= 7
,only installapt-android-7
variants. For android5
and6
,only installapt-android-5
variants.
The APKs forGitHub Releases
will be listed underAssets
drop-down of a release. These are automatically attached when a new version is released.
The APKs forGitHub Build
action workflows will be listed underArtifacts
section of a workflow run. These are created for each commit/push done to the repository and can be used by users who don't want to wait for releases and want to try out the latest features immediately or want to test their pull requests. Note that for action workflows, you need to belogged into aGitHub
accountfor theArtifacts
links to be enabled/clickable. If you are using theGitHub
app,then make sure to open workflow link in a browser like Chrome or Firefox that has your GitHub account logged in since the in-app browser may not be logged in.
The APKs for both of these aredebuggable
and are compatible with each other but they are not compatible with other sources.
Both universal and architecture specific APKs are released. The APK and bootstrap installation size will be~180MB
if using universal and~120MB
if using architecture specific. Checkherefor details.
Security warning:APK files on GitHub are signed with a test key that has beenshared with community.This IS NOT an official developer key and everyone can use it to generate releases for own testing. Be very careful when using Termux GitHub builds obtained elsewhere excepthttps://github.com/termux/termux-app.Everyone is able to use it to forge a malicious Termux update installable over the GitHub build. Think twice about installing Termux builds distributed via Telegram or other social media. If your device get caught by malware, we will not be able to help you.
Thetest keyshall not be used to impersonate @termux and can't be used for this anyway. This key is not trusted by us and it is quite easy to detect its use in user generated content.
Keystore information
Alias name: alias
Creation date: Oct 4, 2019
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=APK Signer, OU=Earth, O=Earth
Issuer: CN=APK Signer, OU=Earth, O=Earth
Serial number: 29be297b
Valid from: Wed Sep 04 02:03:24 EEST 2019 until: Tue Oct 26 02:03:24 EEST 2049
Certificate fingerprints:
SHA1: 51:79:55:EA:BF:69:FC:05:7C:41:C7:D3:79:DB:BC:EF:20:AD:85:F2
SHA256: B6:DA:01:48:0E:EF:D5:FB:F2:CD:37:71:B8:D1:02:1E:C7:91:30:4B:DD:6C:4B:F4:1D:3F:AA:BA:D4:8E:E5:E1
Signature algorithm name: SHA1withRSA (disabled)
Subject Public Key Algorithm: 2048-bit RSA key
Version: 3
There is currently a build of Termux available on Google Play for Android 11+ devices, with extensive adjustments in order to pass policy requirements there. This is under development and has missing functionality and bugs (seeherefor status updates) compared to the stable F-Droid build, which is why most users who can should still use F-Droid or GitHub build as mentioned above.
Currently, Google Play will try to update installations away from F-Droid ones. Updating will still fail assharedUserIdhas been removed. A planned 0.118.1 F-Droid release will fix this by setting a higher version code than used for the PlayStore app. Meanwhile, to prevent Google Play from attempting to download and then fail to install the Google Play releases over existing installations, you can open the Termux apps pages on Google Play and then click on the 3 dots options button in the top right and then disable the Enable auto update toggle. However, the Termux apps updates will still show in the PlayStore app updates list.
If you want to help out with testing the Google Play build (or cannot install Termux from other sources), be aware that it's built from a separate repository (https://github.com/termux-play-store/) - be sure to report issuesthere,as any issues encountered might very well be specific to that repository.
Uninstallation may be required if a user doesn't want Termux installed in their device anymore or is switching to a differentinstall source.You may also want to considerBacking up Termuxbefore the uninstallation.
To uninstall Termux completely, you must uninstallany and all existing Termux or its plugin app APKslisted inTermux App and Plugins.
Go toAndroid Settings
->Applications
and then look for those apps. You can also use the search feature if it’s available on your device and searchtermux
in the applications list.
Even if you think you have not installed any of the plugins, it's strongly suggested to go through the application list in Android settings and double-check.
All community links are availablehere.
The main ones are the following.
- Termux Reddit community
- Termux User Matrix Channel(Gitter)
- Termux Dev Matrix Channel(Gitter)
- Termux X (Twitter)
- Termux Support Email
- FAQ
- Termux File System Layout
- Differences From Linux
- Package Management
- Remote Access
- Backing up Termux
- Terminal Settings
- Touch Keyboard
- Android Storage and Sharing Data with Other Apps
- Android APIs
- Moved Termux Packages Hosting From Bintray to IPFS
- Running Commands in Termux From Other Apps via
RUN_COMMAND
intent - Termux and Android 10
-
VTE (libvte): Terminal emulator widget for GTK+, mainly used in gnome-terminal.Source,Open Issues,andAll (including closed) issues.
-
iTerm 2: OS X terminal application.Source,IssuesandDocumentation(which includesiTerm2 proprietary escape codes).
-
Konsole: KDE terminal application.Source,in particulartests,BugsandWishes.
-
hterm: JavaScript terminal implementation from Chromium.Source,includingtests,andGoogle group.
-
xterm: The grandfather of terminal emulators.Source.
-
Connectbot: Android SSH client.Source
-
Android Terminal Emulator: Android terminal app which Termux terminal handling is based on. Inactive.Source.
You can help debug problems of theTermux
app and its plugins by setting appropriatelogcat
Log Level
inTermux
app settings -><APP_NAME>
->Debugging
->Log Level
(RequiresTermux
app version>= 0.118.0
). TheLog Level
defaults toNormal
and log levelVerbose
currently logs additional information. Its best to revert log level toNormal
after you have finished debugging since private data may otherwise be passed tologcat
during normal operation and moreover, additional logging increases execution time.
The plugin appsdo not execute the commands themselvesbut send execution intents toTermux
app, which has its own log level which can be set inTermux
app settings ->Termux
->Debugging
->Log Level
.So you must set log level for bothTermux
and the respective plugin app settings to get all the info.
Once log levels have been set, you can run thelogcat
command inTermux
app terminal to view the logs in realtime (Ctrl+c
to stop) or uselogcat -d > logcat.txt
to take a dump of the log. You can also view the logs from a PC overADB
.For more information, check official androidlogcat
guidehere.
Moreover, users can generate termux filesstat
info andlogcat
dump automatically too with terminal's long hold options menuMore
->Report Issue
option and selectingYES
in the prompt shown to add debug info. This can be helpful for reporting and debugging other issues. If the report generated is too large, thenSave To File
option in context menu (3 dots on top right) ofReportActivity
can be used and the file viewed/shared instead.
Users must post complete report (optionally without sensitive info) when reporting issues. Issues opened with(partial) screenshots of error reportsinstead of text will likely be automatically closed/deleted.
Off
- Log nothing.Normal
- Start logging error, warn and info messages and stacktraces.Debug
- Start logging debug messages.Verbose
- Start logging verbose messages.
Thetermux-sharedlibrary was added inv0.109
.It defines shared constants and utils of the Termux app and its plugins. It was created to allow for the removal of all hardcoded paths in the Termux app. Some of the termux plugins are using this as well and rest will in future. If you are contributing code that is using a constant or a util that may be shared, then define it intermux-shared
library if it currently doesn't exist and reference it from there. Update the relevant changelogs as well. Pull requests using hardcoded valueswill/should notbe accepted. Termux app and plugin specific classes must be added undercom.termux.shared.termux
package and general classes outside it. Thetermux-shared
LICENSE
must also be checked and updated if necessary when contributing code. The licenses of any external library or code must be honoured.
The main Termux constants are defined byTermuxConstants
class. It also contains information on how to fork Termux or build it with your own package name. Changing the package name will require building the bootstrap zip packages and other packages with the new$PREFIX
,checkBuilding Packagesfor more info.
CheckTermux Librariesfor how to import termux libraries in plugin apps andForking and Local Developmentfor how to update termux libraries for plugins.
TheversionName
inbuild.gradle
files of Termux and its plugin apps must follow thesemantic version2.0.0
specin the formatmajor.minor.patch(-prerelease)(+buildmetadata)
.When bumpingversionName
inbuild.gradle
files and when creating a tag for new releases on GitHub, make sure to include the patch number as well, likev0.1.0
instead of justv0.1
.Thebuild.gradle
files andattach_debug_apks_to_release
workflow validates the version as well and the build/attachment will fail ifversionName
does not follow the spec.
Commit messagesmustuse theConventional Commitsspec so that chagelogs as per theKeep a Changelogspec can automatically be generated by thecreate-conventional-changelog
script, check its repo for further details on the spec.The first letter fortype
anddescription
must be capital and description should be in the present tense.The space after the colon:
is necessary. For a breaking change, add an exclamation mark!
before the colon:
,so that it is highlighted in the chagelog automatically.
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Only thetypes
listed below must be used exactly as they are used in the changelog headings.For example,Added: Add foo
,Added|Fixed: Add foo and fix bar
,Changed!: Change baz as a breaking change
,etc. You can optionally add a scope as well, likeFixed(terminal): Fix some bug
.Do not use anything else as type, likeadd
instead ofAdded
,etc.
- Addedfor new features.
- Changedfor changes in existing functionality.
- Deprecatedfor soon-to-be removed features.
- Removedfor now removed features.
- Fixedfor any bug fixes.
- Securityin case of vulnerabilities.
- Check
TermuxConstants
javadocs for instructions on what changes to make in the app to change package name. - You also need to recompile bootstrap zip for the new package name. Checkbuilding bootstrap,hereandhere.
- Currently, not all plugins use
TermuxConstants
fromtermux-shared
library and have hardcodedcom.termux
values and will need to be manually patched. - If forking termux plugins, checkForking and Local Developmentfor info on how to use termux libraries for plugins.