DOCSEARCHbyAlgolia
Submit Docs

Termux:Widget Documentation

repository·master·Indexed 23 days ago

https://github.com/termux/termux-widget

A plugin for the Termux app that enables the execution of scripts via Android launcher widgets and shortcuts. It supports foreground terminal sessions, background tasks, custom icons for shortcuts, and dynamic shortcuts. The documentation covers installation via F-Droid and GitHub, directory configuration for scripts and icons, widget refreshing methods, debugging via logcat, and fixing shebangs for external scripts.

Tokens
1.3K
Snippets
2
Records
7
Agent score
33%

What's inside Termux:Widget

  1. Fix Shebangs for External Scripts

    master

    Because Termux:Widget sends execution intents to the Termux app, the environment (like LD_PRELOAD) is not fully loaded for external scripts. If an external script uses a standard Linux shebang like #!/usr/bin/bash, it will fail with bad interpreter: No such file or directory.

    Solutions

    1. Use Termux Shebangs: Ensure your scripts use the full path to the Termux binary:
      • Bash: #!/data/data/com.termux/files/usr/bin/bash
    2. Automated Fix: Run the termux-fix-shebang command on your external scripts to update them automatically.
    3. Use Wrapper Scripts: Use tudo (for user context) or sudo (for root context) to run external scripts, as these load the Termux environment properly.

  2. Configure Script Directories for Termux:Widget

    master

    To use the plugin, you must set up specific directories in your Termux home folder with correct permissions. The plugin uses these directories to discover scripts for widgets and shortcuts.

    1. Foreground Scripts (Launcher Shortcuts)

    Scripts in ~/.shortcuts/ run in a foreground terminal session.

    mkdir -p /data/data/com.termux/files/home/.shortcuts
chmod 700 -R /data/data/com.termux/files/home/.shortcuts

    2. Background Scripts (Tasks)

    Scripts in ~/.shortcuts/tasks run in the background and appear as running tasks in the Termux notification.

    mkdir -p /data/data/com.termux/files/home/.shortcuts/tasks
chmod 700 -R /data/data/com.termux/files/home/.shortcuts/tasks

    Requirements:

    • The parent directory must have read permissions for the plugin to see the files.
    • The parent directory must have executable permissions for the scripts to run.
    • Files must be regular files and not broken symlinks. Their canonical path must be under ~/.shortcuts or ~/.termux.
    mkdir -p /data/data/com.termux/files/home/.shortcuts
chmod 700 -R /data/data/com.termux/files/home/.shortcuts

mkdir -p /data/data/com.termux/files/home/.shortcuts/tasks
chmod 700 -R /data/data/com.termux/files/home/.shortcuts/tasks

  3. Refresh Termux:Widget Shortcuts

    master

    If you add or modify scripts, the widget list may not update automatically. You can refresh them using one of these methods:

    1. Manually: Press the refresh button on the widget itself.
    2. In-App: Use the REFRESH button in the 'refresh widgets' section of the Termux:Widget app.
    3. Via Command Line: Run the following command from a Termux terminal (requires version >= 0.13.0):
    # Refresh a specific widget by ID
am broadcast -n com.termux.widget/.TermuxWidgetProvider -a com.termux.widget.ACTION_REFRESH_WIDGET --ei appWidgetId <id>

# Refresh ALL widgets (requires version >= 0.114.0)
am broadcast -n com.termux.widget/.TermuxWidgetProvider -a com.termux.widget.ACTION_REFRESH_WIDGET --ei appWidgetId 0

  4. Add Custom Icons to Launcher Shortcuts

    master

    For version >= 0.12, you can assign custom icons to your launcher shortcuts by placing PNG files in the ~/.shortcuts/icons directory. The icon filename must match the script name followed by .png (e.g., myscript.sh.png).

    Setup

    Create the directory and set permissions:

    mkdir -p /data/data/com.termux/files/home/.shortcuts/icons
chmod -R a-x,u=rwX,go-rwx /data/data/com.termux/files/home/.shortcuts/icons

    Note: The icon must be a regular file and its canonical path must reside under ~/.shortcuts/icons or ~/.termux.

  5. Create Dynamic Shortcuts

    master

    Dynamic shortcuts appear when long-pressing the Termux:Widget app icon or in launcher search results.

    1. Place your desired scripts or binaries in ~/.termux/widget/dynamic_shortcuts.
    2. Open the Termux:Widget app.
    3. Go to the dynamic shortcuts section and tap CREATE SHORTCUTS.

    To remove them, tap REMOVE SHORTCUTS in the same section (this will not remove shortcuts that were already converted to static launcher shortcuts).

  6. Install Termux:Widget

    master

    Termux:Widget is a plugin for the Termux app that allows you to run scripts via launcher shortcuts and widgets.

    Installation Sources

    Warning: Do not install Termux apps from the Google Play Store as they are deprecated and no longer updated due to Android 10 restrictions.

  7. Debug Termux:Widget and Termux

    master

    If shortcuts are not appearing or scripts are not firing, you may need to increase the logging verbosity.

    1. Set Log Levels

    You must set the log level for both apps to see the full execution flow:

    • Termux:Widget: Go to App Settings -> Termux:Widget -> Debugging -> Log Level.
    • Termux: Go to App Settings -> Termux -> Debugging -> Log Level.

    Available Log Levels:

    • Off: Log nothing.
    • Normal: Logs error, warn, info, and stacktraces.
    • Debug: Logs debug messages.
    • Verbose: Logs all messages (highest detail).

    2. View Logs

    Use the logcat command in the Termux terminal to view logs in real-time:

    logcat

    Or dump logs to a file:

    logcat -d > logcat.txt