How to Install and Use Termux:Widget: A Complete Step-by-Step Guide

If you use Termux on Android, you already know how powerful a Linux environment in your pocket can be. But retyping the same long commands every time you want to update packages, run a script, or start a server gets old fast. That's where Termux:Widget comes in — it turns your terminal scripts into tappable shortcuts right on your home screen.

This guide covers everything you need: downloading it correctly, fixing the frustrating Termux:Widget shortcut not showing problem, and running your first script with a single tap.

What Is Termux:Widget?

Termux:Widget is an official add-on app for Termux. Its job is to bridge your Android launcher and your command-line scripts — instead of opening Termux and typing a command, you place a widget on your home screen that runs a script instantly when tapped.

Whether you're automating backups, checking system stats, or launching a local server, this saves real time. Because it depends on specific folder structures and permissions, beginners sometimes hit setup issues — this guide walks through avoiding and fixing them.

Prerequisites Before You Begin

Before installing the widget, make sure your base Termux environment is ready. If you installed Termux from the Google Play Store, stop — that build has historically lagged behind or gone unmaintained. Install from F-Droid or GitHub instead; see our guide on how to install Termux on Android if you haven't already.

Open your terminal and run:

pkg update && pkg upgrade -y
termux-setup-storage

Tap Allow when the storage permission prompt appears. If you're not familiar with why Termux needs this, our Termux storage guide explains the underlying folder structure in more detail.

Step-by-Step Installation Guide

Step 1: Install the Termux:Widget App

Termux:Widget must be installed from the same source as your main Termux app — this isn't a suggestion, it's a hard requirement, since Android verifies matching app signatures for plugins to communicate with the main app. If you installed Termux from F-Droid, download Termux:Widget from F-Droid or the official GitHub releases page — not the Play Store — and install it.

Step 2: Create the Scripts Directory

Termux:Widget only looks for scripts inside one specific hidden folder in your home directory. Create it, and set its permissions correctly — the widget will refuse to display any scripts if this folder is world-readable or world-writable:

mkdir -p ~/.shortcuts
chmod 700 -R ~/.shortcuts

Step 3: Create a Test Script

Let's create a simple script the widget can run — one that updates your packages and shows a success message:

nano ~/.shortcuts/update.sh

Paste the following into nano:

#!/data/data/com.termux/files/usr/bin/bash
pkg update -y
echo "Packages updated successfully!"
read -p "Press Enter to close..."

Save with Ctrl + O, then Enter, then exit with Ctrl + X. If you're new to writing and running scripts like this, our guide on creating and running a Bash script in Termux covers the basics. Now make the script executable:

chmod +x ~/.shortcuts/update.sh

Step 4: Add the Widget to Your Home Screen

Long-press an empty area of your home screen and tap Widgets. Scroll to the Termux section — you'll see widget sizes like 1x1 or 2x2. Drag your preferred size onto your home screen.

A menu will pop up listing the scripts found in your ~/.shortcuts folder. Tap update.sh — your shortcut is ready.

Example Terminal Output

Tapping your new shortcut launches Termux in the background and runs your script. Expect output similar to:

$ /data/data/com.termux/files/home/.shortcuts/update.sh
Hit:1 https://packages.termux.dev/apt/termux-main stable InRelease
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
All packages are up to date.
Packages updated successfully!
Press Enter to close...

Troubleshooting: Termux:Widget Shortcut Not Showing

The most common frustration is opening the widget configuration menu and finding it blank, or hitting the Termux:Widget shortcut not showing issue. Check these causes:

Tips for Advanced Users

• Run scripts silently in the background. Scripts placed in ~/.shortcuts/ open a visible terminal session when tapped. For scripts that should run with no window at all, Termux:Widget also supports a ~/.shortcuts/tasks/ subdirectory — anything placed there runs silently as a background task instead of opening a session.
• Pair with Termux:Styling. This official add-on lets you apply custom color schemes to Termux itself, so your scripts look good when they do open a visible session. If you want to tweak fonts and colors more generally, see our guide on changing Termux font and color.
• Customize widget icons. Some launchers, like Nova Launcher, let you long-press a widget shortcut and change its icon so it looks like a native app.

Frequently Asked Questions

Why can't I see my script in the widget menu?

Usually because the script isn't inside ~/.shortcuts, lacks executable permissions, or the folder itself has incorrect permissions. Run chmod +x ~/.shortcuts/your-script.sh for the script, and chmod 700 -R ~/.shortcuts for the folder.

Can I run Python scripts with Termux:Widget?

Yes. Create a script with a Python shebang (#!/data/data/com.termux/files/usr/bin/python), or call your Python script from a bash wrapper script.

Does Termux:Widget work with the Google Play Store version of Termux?

No, reliably. Because plugin apps rely on matching app signatures to communicate with the main Termux app, mixing an outdated Play Store install with an F-Droid plugin (or vice versa) causes signature mismatches and permission errors. Use the same source — F-Droid or GitHub — for both.

What to Do Next

With Termux:Widget set up, you can turn any script into a one-tap shortcut. To build out more automation, check our guides on using cron jobs in Termux for scheduled tasks and essential Termux commands for beginners to get more comfortable scripting your workflow.