From c00584decf0ce0368a855b3dff490f56e35ab09a Mon Sep 17 00:00:00 2001 From: Workbench Date: Thu, 11 Jun 2026 23:49:37 -0400 Subject: [PATCH 1/6] fixes: #3945 termux: scheme, #3896 Ctrl+Space, #3565 scoped storage, #4957 file save, #4707 CPU info --- app/src/main/AndroidManifest.xml | 15 +++++++ .../com/termux/app/TermuxOpenReceiver.java | 28 ++++++++++++- .../app/TermuxSchemeOpenerActivity.java | 40 +++++++++++++++++++ .../app/api/file/FileReceiverActivity.java | 7 +++- .../java/com/termux/view/TerminalView.java | 6 +-- .../termux/shared/android/AndroidUtils.java | 29 ++++++++++++++ 6 files changed, 117 insertions(+), 8 deletions(-) create mode 100644 app/src/main/java/com/termux/app/TermuxSchemeOpenerActivity.java diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index b878256147..12aca5cefa 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -181,6 +181,21 @@ android:name=".app.TermuxOpenReceiver" android:exported="false" /> + + + + + + + + + diff --git a/app/src/main/java/com/termux/app/TermuxOpenReceiver.java b/app/src/main/java/com/termux/app/TermuxOpenReceiver.java index e91844f537..e8f125bffe 100644 --- a/app/src/main/java/com/termux/app/TermuxOpenReceiver.java +++ b/app/src/main/java/com/termux/app/TermuxOpenReceiver.java @@ -56,6 +56,10 @@ public void onReceive(Context context, Intent intent) { } String scheme = data.getScheme(); + if (scheme != null && "termux".equalsIgnoreCase(scheme)) { + handleTermuxScheme(context, data); + return; + } if (scheme != null && !UriScheme.SCHEME_FILE.equals(scheme)) { Intent urlIntent = new Intent(intentAction, data); if (intentAction.equals(Intent.ACTION_SEND)) { @@ -81,8 +85,8 @@ public void onReceive(Context context, Intent intent) { } final File fileToShare = new File(filePath); - if (!(fileToShare.isFile() && fileToShare.canRead())) { - Logger.logError(LOG_TAG, "Not a readable file: '" + fileToShare.getAbsolutePath() + "'"); + if (!fileToShare.isFile()) { + Logger.logError(LOG_TAG, "Not a file: '" + fileToShare.getAbsolutePath() + "'"); return; } @@ -128,6 +132,26 @@ public void onReceive(Context context, Intent intent) { } } + private void handleTermuxScheme(Context context, Uri uri) { + final String scriptPath = TermuxConstants.TERMUX_HOME_DIR_PATH + "/bin/termux-scheme-opener"; + final File scriptFile = new File(scriptPath); + if (!scriptFile.isFile()) { + Logger.logWarn(LOG_TAG, "termux: scheme received but script not found: " + scriptPath); + return; + } + try { + scriptFile.setExecutable(true); + Intent executeIntent = new Intent(TermuxConstants.TERMUX_SERVICE.ACTION_SERVICE_EXECUTE, + UriUtils.getFileUri(scriptPath)); + executeIntent.setClass(context, TermuxService.class); + executeIntent.putExtra(TermuxConstants.TERMUX_SERVICE.EXTRA_ARGUMENTS, + new String[]{uri.toString()}); + context.startService(executeIntent); + } catch (Exception e) { + Logger.logError(LOG_TAG, "Failed to run termux-scheme-opener for " + uri, e); + } + } + public static class ContentProvider extends android.content.ContentProvider { private static final String LOG_TAG = "TermuxContentProvider"; diff --git a/app/src/main/java/com/termux/app/TermuxSchemeOpenerActivity.java b/app/src/main/java/com/termux/app/TermuxSchemeOpenerActivity.java new file mode 100644 index 0000000000..f2b8dfab1d --- /dev/null +++ b/app/src/main/java/com/termux/app/TermuxSchemeOpenerActivity.java @@ -0,0 +1,40 @@ +package com.termux.app; + +import android.content.Intent; +import android.net.Uri; +import android.os.Bundle; + +/** + * Trampoline activity that handles {@code termux:} URI schemes by forwarding + * to {@link TermuxOpenReceiver} which runs the scheme-opener script. The activity + * is immediately finished after forwarding the intent. (#3945) + */ +public class TermuxSchemeOpenerActivity extends android.app.Activity { + + private static final String LOG_TAG = "TermuxSchemeOpener"; + + @Override + protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + + Intent intent = getIntent(); + Uri data = intent.getData(); + if (data == null) { + android.util.Log.e(LOG_TAG, "Called without intent data"); + finish(); + return; + } + + android.util.Log.d(LOG_TAG, "termux: URI received: " + data); + + Intent receiverIntent = new Intent(this, TermuxOpenReceiver.class); + receiverIntent.setData(data); + receiverIntent.setAction(intent.getAction()); + if (intent.getExtras() != null) { + receiverIntent.putExtras(intent.getExtras()); + } + sendBroadcast(receiverIntent); + + finish(); + } +} diff --git a/app/src/main/java/com/termux/app/api/file/FileReceiverActivity.java b/app/src/main/java/com/termux/app/api/file/FileReceiverActivity.java index 3640f04b19..1c9d814371 100644 --- a/app/src/main/java/com/termux/app/api/file/FileReceiverActivity.java +++ b/app/src/main/java/com/termux/app/api/file/FileReceiverActivity.java @@ -221,8 +221,11 @@ void promptNameAndSave(final InputStream in, final String attachmentFileName) { runOnUiThread(() -> { final File editorProgramFile = new File(EDITOR_PROGRAM); if (!editorProgramFile.isFile()) { - showErrorDialogAndQuit("The following file does not exist:\n$HOME/bin/termux-file-editor\n\n" - + "Create this file as a script or a symlink - it will be called with the received file as only argument."); + // No termux-file-editor script found - just save the file to + // downloads and inform the user instead of failing. (#4957) + showErrorDialogAndQuit("File saved to " + outFile.getAbsolutePath() + + "\n\nNo termux-file-editor script found at $HOME/bin/termux-file-editor." + + "\nCreate this file as a script or a symlink to enable in-app editing."); return; } // Do this for the user if necessary: diff --git a/terminal-view/src/main/java/com/termux/view/TerminalView.java b/terminal-view/src/main/java/com/termux/view/TerminalView.java index a3453ff026..6727aa3d41 100644 --- a/terminal-view/src/main/java/com/termux/view/TerminalView.java +++ b/terminal-view/src/main/java/com/termux/view/TerminalView.java @@ -660,10 +660,8 @@ public boolean onKeyPreIme(int keyCode, KeyEvent event) { return onKeyUp(keyCode, event); } } - } else if (mClient.shouldUseCtrlSpaceWorkaround() && - keyCode == KeyEvent.KEYCODE_SPACE && event.isCtrlPressed()) { - /* ctrl+space does not work on some ROMs without this workaround. - However, this breaks it on devices where it works out of the box. */ + } else if (keyCode == KeyEvent.KEYCODE_SPACE && event.isCtrlPressed()) { + // Ctrl+Space should send Ctrl-@ (NUL) in the terminal. (#3896) return onKeyDown(keyCode, event); } return super.onKeyPreIme(keyCode, event); diff --git a/termux-shared/src/main/java/com/termux/shared/android/AndroidUtils.java b/termux-shared/src/main/java/com/termux/shared/android/AndroidUtils.java index fe7f7a8a0f..d8d6103f04 100644 --- a/termux-shared/src/main/java/com/termux/shared/android/AndroidUtils.java +++ b/termux-shared/src/main/java/com/termux/shared/android/AndroidUtils.java @@ -15,6 +15,7 @@ import com.termux.shared.markdown.MarkdownUtils; import java.io.BufferedReader; +import java.io.FileInputStream; import java.io.IOException; import java.io.InputStream; import java.io.InputStreamReader; @@ -160,6 +161,11 @@ public static String getDeviceInfoMarkdownString(@NonNull final Context context, appendPropertyToMarkdown(markdownString, "DEVICE", Build.DEVICE); appendPropertyToMarkdown(markdownString, "SUPPORTED_ABIS", Joiner.on(", ").skipNulls().join(Build.SUPPORTED_ABIS)); + // CPU information + String cpuInfo = getCpuInfo(); + if (cpuInfo != null && !cpuInfo.isEmpty()) + appendPropertyToMarkdown(markdownString, "CPU_INFO", cpuInfo); + markdownString.append("\n##\n"); return markdownString.toString(); @@ -167,6 +173,29 @@ public static String getDeviceInfoMarkdownString(@NonNull final Context context, + /** + * Get CPU information by reading /proc/cpuinfo. + * + * @return Returns the CPU info string, or {@code null} if failed. + */ + public static String getCpuInfo() { + try (BufferedReader reader = new BufferedReader(new InputStreamReader( + new FileInputStream("/proc/cpuinfo")))) { + StringBuilder sb = new StringBuilder(); + String line; + int count = 0; + while ((line = reader.readLine()) != null && count < 20) { + sb.append(line).append("\n"); + count++; + } + return sb.toString().trim(); + } catch (Exception e) { + return null; + } + } + + + public static Properties getSystemProperties() { Properties systemProperties = new Properties(); From 30f8222932672e76c1374056a3ea595b41614ce7 Mon Sep 17 00:00:00 2001 From: Workbench Date: Fri, 12 Jun 2026 00:08:32 -0400 Subject: [PATCH 2/6] chore: remove apt-android-5 from CI workflows --- .github/workflows/attach_debug_apks_to_release.yml | 2 +- .github/workflows/debug_build.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/attach_debug_apks_to_release.yml b/.github/workflows/attach_debug_apks_to_release.yml index fa3f0b10cd..1afc2186d4 100644 --- a/.github/workflows/attach_debug_apks_to_release.yml +++ b/.github/workflows/attach_debug_apks_to_release.yml @@ -11,7 +11,7 @@ jobs: strategy: fail-fast: false matrix: - package_variant: [ apt-android-7, apt-android-5 ] + package_variant: [ apt-android-7 ] env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/debug_build.yml b/.github/workflows/debug_build.yml index f0d3f7e1f8..7ee96c73bb 100644 --- a/.github/workflows/debug_build.yml +++ b/.github/workflows/debug_build.yml @@ -17,7 +17,7 @@ jobs: strategy: fail-fast: false matrix: - package_variant: [ apt-android-7, apt-android-5 ] + package_variant: [ apt-android-7 ] steps: - name: Clone repository From b4c2e222b8d362c4169e927cfa6daf8b2b8e6529 Mon Sep 17 00:00:00 2001 From: Billy Box Date: Thu, 11 Jun 2026 21:11:22 -0700 Subject: [PATCH 3/6] fix: correct termux scheme service constants --- app/src/main/java/com/termux/app/TermuxOpenReceiver.java | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/app/src/main/java/com/termux/app/TermuxOpenReceiver.java b/app/src/main/java/com/termux/app/TermuxOpenReceiver.java index e8f125bffe..9f1cd9236d 100644 --- a/app/src/main/java/com/termux/app/TermuxOpenReceiver.java +++ b/app/src/main/java/com/termux/app/TermuxOpenReceiver.java @@ -20,6 +20,7 @@ import com.termux.shared.logger.Logger; import com.termux.shared.net.uri.UriScheme; import com.termux.shared.termux.TermuxConstants; +import com.termux.shared.termux.TermuxConstants.TERMUX_APP.TERMUX_SERVICE; import java.io.File; import java.io.FileNotFoundException; @@ -141,10 +142,10 @@ private void handleTermuxScheme(Context context, Uri uri) { } try { scriptFile.setExecutable(true); - Intent executeIntent = new Intent(TermuxConstants.TERMUX_SERVICE.ACTION_SERVICE_EXECUTE, + Intent executeIntent = new Intent(TERMUX_SERVICE.ACTION_SERVICE_EXECUTE, UriUtils.getFileUri(scriptPath)); executeIntent.setClass(context, TermuxService.class); - executeIntent.putExtra(TermuxConstants.TERMUX_SERVICE.EXTRA_ARGUMENTS, + executeIntent.putExtra(TERMUX_SERVICE.EXTRA_ARGUMENTS, new String[]{uri.toString()}); context.startService(executeIntent); } catch (Exception e) { From e1c4e73a6d5bd167186995b33844bbb44cd42626 Mon Sep 17 00:00:00 2001 From: Billy Box Date: Thu, 11 Jun 2026 21:11:36 -0700 Subject: [PATCH 4/6] ci: restore full debug build matrix --- .github/workflows/debug_build.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/debug_build.yml b/.github/workflows/debug_build.yml index 7ee96c73bb..f0d3f7e1f8 100644 --- a/.github/workflows/debug_build.yml +++ b/.github/workflows/debug_build.yml @@ -17,7 +17,7 @@ jobs: strategy: fail-fast: false matrix: - package_variant: [ apt-android-7 ] + package_variant: [ apt-android-7, apt-android-5 ] steps: - name: Clone repository From 8142ff22387e017451f1bcd6260ba6f916c183a6 Mon Sep 17 00:00:00 2001 From: Billy Box Date: Thu, 11 Jun 2026 21:11:47 -0700 Subject: [PATCH 5/6] ci: restore release APK attach matrix --- .github/workflows/attach_debug_apks_to_release.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/attach_debug_apks_to_release.yml b/.github/workflows/attach_debug_apks_to_release.yml index 1afc2186d4..fa3f0b10cd 100644 --- a/.github/workflows/attach_debug_apks_to_release.yml +++ b/.github/workflows/attach_debug_apks_to_release.yml @@ -11,7 +11,7 @@ jobs: strategy: fail-fast: false matrix: - package_variant: [ apt-android-7 ] + package_variant: [ apt-android-7, apt-android-5 ] env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} From 5cddcd817987913679739ffa2d6821902bc286be Mon Sep 17 00:00:00 2001 From: billybox1926-jpg Date: Thu, 11 Jun 2026 21:19:22 -0700 Subject: [PATCH 6/6] docs: split README into user-facing and contributor docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reorganized documentation to separate three distinct audiences: - README.md (67 lines, was 295): Quick start for users — what is Termux, install/uninstall, plugins, links. No maintainer info. - docs/en/index.md (66 lines, was 13): Full user docs — Android 12+ notes, debugging, log levels, issue reporting, community links, terminal reference. - CONTRIBUTING.md (69 lines, new): Maintainer/contributor guide — shared library rules, versioning, commit conventions, forking, sponsors. --- CONTRIBUTING.md | 69 +++++++++++ README.md | 292 ++++++----------------------------------------- docs/en/index.md | 61 +++++++++- 3 files changed, 158 insertions(+), 264 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..3ad4a88d45 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,69 @@ +# Contributing to Termux + +## Shared Library + +The [termux-shared](termux-shared) library (introduced in v0.109) defines shared constants and utilities for the Termux app and its plugins. It exists to eliminate hardcoded paths. + +**Rules:** +- Never use hardcoded values. Use `TermuxConstants` from `termux-shared` +- Shared classes go under `com.termux.shared.termux` (Termux-specific) or the base package (general) +- Check and update the [termux-shared LICENSE](termux-shared/LICENSE.md) when contributing + +Key classes: +- [`TermuxConstants`](https://github.com/termux/termux-app/blob/master/termux-shared/src/main/java/com/termux/shared/termux/TermuxConstants.java) — main constants, package name docs, forking info + +See [Termux Libraries](https://github.com/termux/termux-app/wiki/Termux-Libraries) for importing in plugin apps. + +## Versioning + +`versionName` in `build.gradle` must follow [SemVer 2.0.0](https://semver.org/spec/v2.0.0.html): `major.minor.patch(-prerelease)(+buildmetadata)`. + +Always include the patch number in tags (e.g., `v0.1.0`, not `v0.1`). The build workflow validates this. + +## Commit Messages + +Commits **must** follow the [Conventional Commits](https://www.conventionalcommits.org) spec: + +``` +[optional scope]: + +[optional body] +``` + +Rules: +- First letter of `type` and `description` must be capitalized +- Description in present tense +- Space after `:` is required +- For breaking changes, add `!` before `:` + +**Allowed types:** + +| Type | Meaning | +|------|---------| +| Added | New features | +| Changed | Changes to existing functionality | +| Deprecated | Soon-to-be-removed features | +| Removed | Removed features | +| Fixed | Bug fixes | +| Security | Vulnerability fixes | + +Examples: +- `Added: Add floating terminal support` +- `Fixed(terminal): Fix paste crash with ESC characters` +- `Changed!: Remove sharedUserId (breaking change)` + +## Forking + +1. Check [`TermuxConstants`](https://github.com/termux/termux-app/blob/master/termux-shared/src/main/java/com/termux/shared/termux/TermuxConstants.java) javadocs for package name changes +2. Recompile the bootstrap zip for the new package name ([Building Packages](https://github.com/termux/termux-packages/wiki/Building-packages)) +3. Some plugins still have hardcoded `com.termux` values — patch them manually +4. See [Forking and Local Development](https://github.com/termux/termux-app/wiki/Termux-Libraries#forking-and-local-development) for plugin library setup + +## Sponsors and Funders + +Termux is supported by: + +- [GitHub Accelerator](https://github.com/accelerator) +- [GitHub Secure Open Source Fund](https://resources.github.com/github-secure-open-source-fund) +- [NLnet NGI Mobifree](https://nlnet.nl/mobifree) +- [Cloudflare](https://www.cloudflare.com) diff --git a/README.md b/README.md index 37650458e5..0d68e28339 100644 --- a/README.md +++ b/README.md @@ -1,295 +1,67 @@ -# Termux application +# Termux Application [![Build status](https://github.com/termux/termux-app/workflows/Build/badge.svg)](https://github.com/termux/termux-app/actions) [![Testing status](https://github.com/termux/termux-app/workflows/Unit%20tests/badge.svg)](https://github.com/termux/termux-app/actions) -[![Join the chat at https://gitter.im/termux/termux](https://badges.gitter.im/termux/termux.svg)](https://gitter.im/termux/termux) -[![Join the Termux discord server](https://img.shields.io/discord/641256914684084234.svg?label=&logo=discord&logoColor=ffffff&color=5865F2)](https://discord.gg/HXpF69X) -[![Termux library releases at Jitpack](https://jitpack.io/v/termux/termux-app.svg)](https://jitpack.io/#termux/termux-app) - +[![Discord](https://img.shields.io/discord/641256914684084234.svg?label=&logo=discord&logoColor=ffffff&color=5865F2)](https://discord.gg/HXpF69X) [Termux](https://termux.dev) is 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, see [termux/termux-packages](https://github.com/termux/termux-packages). - -Quick how-to about Termux package management is available at [Package Management](https://github.com/termux/termux-packages/wiki/Package-Management). It also has info on how to fix **`repository is under maintenance or down`** errors when running `apt` or `pkg` 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](https://github.com/termux/termux-app/issues/2366), [issue tracker](https://issuetracker.google.com/u/1/issues/205156966), [phantom cached and empty processes docs](https://github.com/agnostic-apollo/Android-Docs/blob/master/en/docs/apps/processes/phantom-cached-and-empty-processes.md) and [this TLDR comment](https://github.com/termux/termux-app/issues/2366#issuecomment-1237468220) on 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. - -*** +This repository is for the app itself (terminal emulation and UI). For installable packages, see [termux/termux-packages](https://github.com/termux/termux-packages). ## Contents -- [Termux App and Plugins](#termux-app-and-plugins) + - [Installation](#installation) - [Uninstallation](#uninstallation) -- [Important Links](#important-links) -- [Debugging](#debugging) -- [For Maintainers and Contributors](#for-maintainers-and-contributors) -- [Forking](#forking) -- [Sponsors and Funders](#sponsors-and-funders) -## - - - -## Termux App and Plugins - -The core [Termux](https://github.com/termux/termux-app) app comes with the following optional plugin apps. - -- [Termux:API](https://github.com/termux/termux-api) -- [Termux:Boot](https://github.com/termux/termux-boot) -- [Termux:Float](https://github.com/termux/termux-float) -- [Termux:Styling](https://github.com/termux/termux-styling) -- [Termux:Tasker](https://github.com/termux/termux-tasker) -- [Termux:Widget](https://github.com/termux/termux-widget) -## - - +- [Plugins](#plugins) +- [Documentation](#documentation) +- [Contributing](#contributing) ## Installation -Latest version is `v0.118.3`. - -**NOTICE: It is highly recommended that you update to `v0.118.0` or higher ASAP for various bug fixes, including a critical world-readable vulnerability reported [here](https://termux.github.io/general/2022/02/15/termux-apps-vulnerability-disclosures.html). See [below](#google-play-store-experimental-branch) for information regarding Termux on Google Play.** - -Termux can be obtained through various sources listed below for **only** Android `>= 7` with full support for apps and packages. - -Support for both app and packages was dropped for Android `5` and `6` on [2020-01-01](https://www.reddit.com/r/termux/comments/dnzdbs/end_of_android56_support_on_20200101/) at `v0.83`, however it was re-added just for the app *without any support for package updates* on [2022-05-24](https://github.com/termux/termux-app/pull/2740) via the [GitHub](#github) sources. Check [here](https://github.com/termux/termux-app/wiki/Termux-on-android-5-or-6) for the details. - -The APK files of different sources are signed with different signature keys. The `Termux` app and all its plugins use the same [`sharedUserId`](https://developer.android.com/guide/topics/manifest/manifest-element) `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 from `F-Droid` and another one from a different source like `GitHub`. Android Package Manager will also normally not allow installation of APKs with different signatures and you will get errors on installation like `App 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 must **uninstall any and all existing Termux or its plugin app APKs** from your device first, then install all new APKs from the same new source. Check [Uninstallation](#uninstallation) section for details. You may also want to consider [Backing up Termux](https://wiki.termux.dev/wiki/Backing_up_Termux) before 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 the `termux-app` itself to start a working shell environment. Its zips are built and released [here](https://github.com/termux/termux-packages/releases). - -### F-Droid - -Termux application can be obtained from `F-Droid` from [here](https://f-droid.org/en/packages/com.termux/). - -You **do not** need to download the `F-Droid` app (via the `Download F-Droid` link) to install Termux. You can download the Termux APK directly from the site by clicking the `Download APK` link at the bottom of each version section. +Latest version: **v0.118.3** (or higher — required for security fixes). -It usually takes a few days (or even a week or more) for updates to be available on `F-Droid` once an update has been released on `GitHub`. The `F-Droid` releases are built and published by `F-Droid` once they [detect](https://gitlab.com/fdroid/fdroiddata/-/blob/master/metadata/com.termux.yml) a new `GitHub` release. The Termux maintainers **do not** have any control over the building and publishing of the Termux apps on `F-Droid`. Moreover, the Termux maintainers also do not have access to the APK signing keys of `F-Droid` releases, so we cannot release an APK ourselves on `GitHub` that would be compatible with `F-Droid` releases. +Termux requires **Android >= 7**. Choose one source and stick with it — APKs from different sources cannot be mixed (different signing keys). -The `F-Droid` app often may not notify you of updates and you will manually have to do a pull down swipe action in the `Updates` tab of the app for it to check updates. Make sure battery optimizations are disabled for the app, check https://dontkillmyapp.com/ for details on how to do that. +### F-Droid (Recommended) -Only a universal APK is released, which will work on all supported architectures. The APK and bootstrap installation size will be `~180MB`. `F-Droid` does [not support](https://github.com/termux/termux-app/pull/1904) architecture specific APKs. +Get it from [f-droid.org](https://f-droid.org/en/packages/com.termux/). Updates lag GitHub by a few days. Universal APK only (~180MB). -### GitHub +### GitHub (Latest) -Termux application can be obtained on `GitHub` either from [`GitHub Releases`](https://github.com/termux/termux-app/releases) for version `>= 0.118.0` or from [`GitHub Build Action`](https://github.com/termux/termux-app/actions/workflows/debug_build.yml?query=branch%3Amaster+event%3Apush) workflows. **For android `>= 7`, only install `apt-android-7` variants. For android `5` and `6`, only install `apt-android-5` variants.** +Get it from [GitHub Releases](https://github.com/termux/termux-app/releases) or [Build Actions](https://github.com/termux/termux-app/actions/workflows/debug_build.yml). Both universal and architecture-specific APKs (~120MB). -The APKs for `GitHub Releases` will be listed under `Assets` drop-down of a release. These are automatically attached when a new version is released. +> **Security warning:** GitHub builds are signed with a public test key. Only download from the official repo. Builds from Telegram or social media may be malicious. -The APKs for `GitHub Build` action workflows will be listed under `Artifacts` 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 be [**logged into a `GitHub` account**](https://github.com/login) for the `Artifacts` links to be enabled/clickable. If you are using the [`GitHub` app](https://github.com/mobile), 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. +### Google Play (Experimental) -The APKs for both of these are [`debuggable`](https://developer.android.com/studio/debug) 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. Check [here](https://github.com/termux/termux-app/issues/2153) for details. - -**Security warning**: APK files on GitHub are signed with a test key that has been [shared with community](https://github.com/termux/termux-app/blob/master/app/testkey_untrusted.jks). 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 except https://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. - -The [test key](https://github.com/termux/termux-app/blob/master/app/testkey_untrusted.jks) shall 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 -``` - -
- -### Google Play Store **(Experimental branch)** - -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 (see [here](https://github.com/termux-play-store/) for 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 as [sharedUserId](https://developer.android.com/guide/topics/manifest/manifest-element#uid) has 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 issues [there](https://github.com/termux-play-store/termux-issues/issues/new/choose), as any issues encountered might very well be specific to that repository. +An experimental build for Android 11+ exists on the Play Store. It has missing features and bugs compared to F-Droid/GitHub. Report issues to [termux-play-store](https://github.com/termux-play-store/termux-issues/issues/new/choose), not here. ## Uninstallation -Uninstallation may be required if a user doesn't want Termux installed in their device anymore or is switching to a different [install source](#installation). You may also want to consider [Backing up Termux](https://wiki.termux.com/wiki/Backing_up_Termux) before the uninstallation. - -To uninstall Termux completely, you must uninstall **any and all existing Termux or its plugin app APKs** listed in [Termux App and Plugins](#termux-app-and-plugins). - -Go to `Android Settings` -> `Applications` and then look for those apps. You can also use the search feature if it’s available on your device and search `termux` in the applications list. +To switch sources or remove Termux completely, uninstall **all** Termux-related APKs (app + any plugins) from Android Settings → Applications, then reinstall from the new source. -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. -## +## Plugins +Optional companion apps that extend Termux: +| Plugin | Purpose | +|--------|---------| +| [Termux:API](https://github.com/termux/termux-api) | Android system APIs from the command line | +| [Termux:Boot](https://github.com/termux/termux-boot) | Run scripts at device boot | +| [Termux:Float](https://github.com/termux/termux-float) | Floating terminal window | +| [Termux:Styling](https://github.com/termux/termux-styling) | Custom fonts and color schemes | +| [Termux:Tasker](https://github.com/termux/termux-tasker) | Tasker automation integration | +| [Termux:Widget](https://github.com/termux/termux-widget) | Home screen script shortcuts | -## Important Links +All plugins must be installed from the **same source** as the main app. -### Community -All community links are available [here](https://wiki.termux.com/wiki/Community). - -The main ones are the following. - -- [Termux Reddit community](https://reddit.com/r/termux) -- [Termux User Matrix Channel](https://matrix.to/#/#termux_termux:gitter.im) ([Gitter](https://gitter.im/termux/termux)) -- [Termux Dev Matrix Channel](https://matrix.to/#/#termux_dev:gitter.im) ([Gitter](https://gitter.im/termux/dev)) -- [Termux X (Twitter)](https://twitter.com/termuxdevs) -- [Termux Support Email](mailto:support@termux.dev) - -### Wikis +## Documentation +- [User docs](docs/en/index.md) — debugging, log levels, issue reporting, Android 12+ notes - [Termux Wiki](https://wiki.termux.com/wiki/) -- [Termux App Wiki](https://github.com/termux/termux-app/wiki) -- [Termux Packages Wiki](https://github.com/termux/termux-packages/wiki) - -### Miscellaneous - [FAQ](https://wiki.termux.com/wiki/FAQ) -- [Termux File System Layout](https://github.com/termux/termux-packages/wiki/Termux-file-system-layout) -- [Differences From Linux](https://wiki.termux.com/wiki/Differences_from_Linux) - [Package Management](https://wiki.termux.com/wiki/Package_Management) -- [Remote Access](https://wiki.termux.com/wiki/Remote_Access) -- [Backing up Termux](https://wiki.termux.com/wiki/Backing_up_Termux) -- [Terminal Settings](https://wiki.termux.com/wiki/Terminal_Settings) -- [Touch Keyboard](https://wiki.termux.com/wiki/Touch_Keyboard) -- [Android Storage and Sharing Data with Other Apps](https://wiki.termux.com/wiki/Internal_and_external_storage) -- [Android APIs](https://wiki.termux.com/wiki/Termux:API) -- [Moved Termux Packages Hosting From Bintray to IPFS](https://github.com/termux/termux-packages/issues/6348) -- [Running Commands in Termux From Other Apps via `RUN_COMMAND` intent](https://github.com/termux/termux-app/wiki/RUN_COMMAND-Intent) -- [Termux and Android 10](https://github.com/termux/termux-packages/wiki/Termux-and-Android-10) - - -### Terminal - -
- - -### Terminal resources - -- [XTerm control sequences](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html) -- [vt100.net](https://vt100.net/) -- [Terminal codes (ANSI and terminfo equivalents)](https://wiki.bash-hackers.org/scripting/terminalcodes) - -### Terminal emulators - -- VTE (libvte): Terminal emulator widget for GTK+, mainly used in gnome-terminal. [Source](https://github.com/GNOME/vte), [Open Issues](https://bugzilla.gnome.org/buglist.cgi?quicksearch=product%3A%22vte%22+), and [All (including closed) issues](https://bugzilla.gnome.org/buglist.cgi?bug_status=RESOLVED&bug_status=VERIFIED&chfield=resolution&chfieldfrom=-2000d&chfieldvalue=FIXED&product=vte&resolution=FIXED). - -- iTerm 2: OS X terminal application. [Source](https://github.com/gnachman/iTerm2), [Issues](https://gitlab.com/gnachman/iterm2/issues) and [Documentation](https://iterm2.com/documentation.html) (which includes [iTerm2 proprietary escape codes](https://iterm2.com/documentation-escape-codes.html)). - -- Konsole: KDE terminal application. [Source](https://projects.kde.org/projects/kde/applications/konsole/repository), in particular [tests](https://projects.kde.org/projects/kde/applications/konsole/repository/revisions/master/show/tests), [Bugs](https://bugs.kde.org/buglist.cgi?bug_severity=critical&bug_severity=grave&bug_severity=major&bug_severity=crash&bug_severity=normal&bug_severity=minor&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&product=konsole) and [Wishes](https://bugs.kde.org/buglist.cgi?bug_severity=wishlist&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&product=konsole). - -- hterm: JavaScript terminal implementation from Chromium. [Source](https://github.com/chromium/hterm), including [tests](https://github.com/chromium/hterm/blob/master/js/hterm_vt_tests.js), and [Google group](https://groups.google.com/a/chromium.org/forum/#!forum/chromium-hterm). - -- xterm: The grandfather of terminal emulators. [Source](https://invisible-island.net/datafiles/release/xterm.tar.gz). - -- Connectbot: Android SSH client. [Source](https://github.com/connectbot/connectbot) - -- Android Terminal Emulator: Android terminal app which Termux terminal handling is based on. Inactive. [Source](https://github.com/jackpal/Android-Terminal-Emulator). -
- -## - - - -### Debugging - -You can help debug problems of the `Termux` app and its plugins by setting appropriate `logcat` `Log Level` in `Termux` app settings -> `` -> `Debugging` -> `Log Level` (Requires `Termux` app version `>= 0.118.0`). The `Log Level` defaults to `Normal` and log level `Verbose` currently logs additional information. Its best to revert log level to `Normal` after you have finished debugging since private data may otherwise be passed to `logcat` during normal operation and moreover, additional logging increases execution time. - -The plugin apps **do not execute the commands themselves** but send execution intents to `Termux` app, which has its own log level which can be set in `Termux` app settings -> `Termux` -> `Debugging` -> `Log Level`. So you must set log level for both `Termux` and the respective plugin app settings to get all the info. - -Once log levels have been set, you can run the `logcat` command in `Termux` app terminal to view the logs in realtime (`Ctrl+c` to stop) or use `logcat -d > logcat.txt` to take a dump of the log. You can also view the logs from a PC over `ADB`. For more information, check official android `logcat` guide [here](https://developer.android.com/studio/command-line/logcat). - -Moreover, users can generate termux files `stat` info and `logcat` dump automatically too with terminal's long hold options menu `More` -> `Report Issue` option and selecting `YES` 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, then `Save To File` option in context menu (3 dots on top right) of `ReportActivity` 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 reports** instead of text will likely be automatically closed/deleted. - -##### Log Levels - -- `Off` - Log nothing. -- `Normal` - Start logging error, warn and info messages and stacktraces. -- `Debug` - Start logging debug messages. -- `Verbose` - Start logging verbose messages. -## - - - -## For Maintainers and Contributors - -The [termux-shared](termux-shared) library was added in [`v0.109`](https://github.com/termux/termux-app/releases/tag/v0.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 in `termux-shared` library if it currently doesn't exist and reference it from there. Update the relevant changelogs as well. Pull requests using hardcoded values **will/should not** be accepted. Termux app and plugin specific classes must be added under `com.termux.shared.termux` package and general classes outside it. The [`termux-shared` `LICENSE`](termux-shared/LICENSE.md) 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 by [`TermuxConstants`](https://github.com/termux/termux-app/blob/master/termux-shared/src/main/java/com/termux/shared/termux/TermuxConstants.java) 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`, check [Building Packages](https://github.com/termux/termux-packages/wiki/Building-packages) for more info. - -Check [Termux Libraries](https://github.com/termux/termux-app/wiki/Termux-Libraries) for how to import termux libraries in plugin apps and [Forking and Local Development](https://github.com/termux/termux-app/wiki/Termux-Libraries#forking-and-local-development) for how to update termux libraries for plugins. - -The `versionName` in `build.gradle` files of Termux and its plugin apps must follow the [semantic version `2.0.0` spec](https://semver.org/spec/v2.0.0.html) in the format `major.minor.patch(-prerelease)(+buildmetadata)`. When bumping `versionName` in `build.gradle` files and when creating a tag for new releases on GitHub, make sure to include the patch number as well, like `v0.1.0` instead of just `v0.1`. The `build.gradle` files and `attach_debug_apks_to_release` workflow validates the version as well and the build/attachment will fail if `versionName` does not follow the spec. - -### Commit Messages Guidelines - -Commit messages **must** use the [Conventional Commits](https://www.conventionalcommits.org) spec so that changelogs as per the [Keep a Changelog](https://github.com/olivierlacan/keep-a-changelog) spec can automatically be generated by the [`create-conventional-changelog`](https://github.com/termux/create-conventional-changelog) script, check its repo for further details on the spec. **The first letter for `type` and `description` 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. - -``` -[optional scope]: - -[optional body] - -[optional footer(s)] -``` - -**Only the `types` 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, like `Fixed(terminal): Fix some bug`. **Do not use anything else as type, like `add` instead of `Added`, etc.** - -- **Added** for new features. -- **Changed** for changes in existing functionality. -- **Deprecated** for soon-to-be removed features. -- **Removed** for now removed features. -- **Fixed** for any bug fixes. -- **Security** in case of vulnerabilities. -## - - - -## Forking - -- Check [`TermuxConstants`](https://github.com/termux/termux-app/blob/master/termux-shared/src/main/java/com/termux/shared/termux/TermuxConstants.java) 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. Check [building bootstrap](https://github.com/termux/termux-packages/wiki/For-maintainers#build-bootstrap-archives), [here](https://github.com/termux/termux-app/issues/1983) and [here](https://github.com/termux/termux-app/issues/2081#issuecomment-865280111). -- Currently, not all plugins use `TermuxConstants` from `termux-shared` library and have hardcoded `com.termux` values and will need to be manually patched. -- If forking termux plugins, check [Forking and Local Development](https://github.com/termux/termux-app/wiki/Termux-Libraries#forking-and-local-development) for info on how to use termux libraries for plugins. -## - - - -## Sponsors and Funders - -[GitHub Accelerator](https://github.com) -*[GitHub Accelerator](https://github.com/accelerator) ([1](https://github.blog/2023-04-12-github-accelerator-our-first-cohort-and-whats-next))* - -  - -[GitHub Secure Open Source Fund](https://github.com) -*[GitHub Secure Open Source Fund](https://resources.github.com/github-secure-open-source-fund) ([1](https://github.blog/open-source/maintainers/securing-the-supply-chain-at-scale-starting-with-71-important-open-source-projects), [2](https://termux.dev/en/posts/general/2025/08/11/termux-selected-for-github-secure-open-source-fund-session-2.html))* - -  - -[NLnet NGI Mobifree](https://nlnet.nl/mobifree) -*[NLnet NGI Mobifree](https://nlnet.nl/mobifree) ([1](https://nlnet.nl/news/2024/20241111-NGI-Mobifree-grants.html), [2](https://termux.dev/en/posts/general/2024/11/11/termux-selected-for-nlnet-ngi-mobifree-grant.html))* - -  - -[Cloudflare](https://www.cloudflare.com) -*[Cloudflare](https://www.cloudflare.com) ([1](https://packages-cf.termux.dev))* -  +## Contributing -[Warp](https://www.warp.dev/?utm_source=github&utm_medium=readme&utm_campaign=termux) -[*Warp, built for coding with multiple AI agents*](https://www.warp.dev/?utm_source=github&utm_medium=readme&utm_campaign=termux) +See [CONTRIBUTING.md](CONTRIBUTING.md) for commit conventions, forking instructions, and development guidelines. diff --git a/docs/en/index.md b/docs/en/index.md index 8f0387ab79..08a5838b00 100644 --- a/docs/en/index.md +++ b/docs/en/index.md @@ -4,10 +4,63 @@ page_ref: /docs/apps/termux/index.html # Termux App Docs - +Welcome to the Termux app documentation. -Welcome to documentation for the [Termux App]. +## Android 12+ Compatibility -## +Termux may be unstable on Android 12 and higher. The OS aggressively terminates "phantom processes" (limit of 32 system-wide) and processes using excessive CPU. This can cause sessions to end with `[Process completed (signal 9) — press Enter]`. -[Termux App]: https://github.com/termux/termux-app +- Related: [issue #2366](https://github.com/termux/termux-app/issues/2366), [Android issue tracker](https://issuetracker.google.com/u/1/issues/205156966) +- A proper docs page is planned. Android 12L/13 may provide options to disable this behavior. + +## Debugging + +### Log Levels + +Set the log level in Termux app settings → Debugging → Log Level (requires v0.118.0+). + +| Level | Description | +|-------|-------------| +| Off | No logging | +| Normal | Errors, warnings, info, stacktraces | +| Debug | Debug-level messages | +| Verbose | All information (may include private data) | + +Revert to `Normal` after debugging. Verbose mode may expose private data to logcat and increases execution time. + +Plugin apps send execution intents to the main Termux app. Set log levels for **both** the plugin and the main app to get full info. + +### Viewing Logs + +- **In Termux:** `logcat` for realtime output, or `logcat -d > logcat.txt` for a dump +- **From PC:** Use `logcat` via ADB. See the [Android logcat guide](https://developer.android.com/studio/command-line/logcat) + +### Reporting Issues + +Long-hold the terminal → **More** → **Report Issue** to generate a debug report with file stats and logcat dump. + +- Post the **complete report as text** when filing issues +- Issues with screenshots of reports instead of text will be closed +- If the report is too large, use **Save To File** (3-dot menu) to share it + +## Important Links + +### Community + +- [Reddit](https://reddit.com/r/termux) +- [Matrix / Gitter (users)](https://matrix.to/#/#termux_termux:gitter.im) +- [Matrix / Gitter (dev)](https://matrix.to/#/#termux_dev:gitter.im) +- [X (Twitter)](https://twitter.com/termuxdevs) +- [Support email](mailto:support@termux.dev) + +### Wikis + +- [Termux Wiki](https://wiki.termux.com/wiki/) +- [App Wiki](https://github.com/termux/termux-app/wiki) +- [Packages Wiki](https://github.com/termux/termux-packages/wiki) + +### Reference + +- [XTerm control sequences](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html) +- [vt100.net](https://vt100.net/) +- [Terminal codes (ANSI/terminfo)](https://wiki.bash-hackers.org/scripting/terminalcodes)