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

If you use Termux on your Android device, you already know how powerful a Linux environment in your pocket can be. But typing out long commands every single time you want to update your packages, run a Python script, or start a server gets old fast. That is where Termux:Widget comes in. It lets you turn complex terminal scripts into simple shortcuts right on your home screen.

In this guide, we will walk through everything you need to know about setting it up. You will learn how to download it properly, fix common issues—including the frustrating termux widget shortcut not showing error—and execute your first script with a single tap.

What is Termux:Widget?

Termux:Widget is an official add-on application for the Termux terminal emulator. Its sole purpose is to bridge the gap between your Android launcher and your command-line scripts. Instead of opening Termux, typing a command, and waiting, you can place a widget on your phone screen that runs your favorite scripts instantly.

Whether you want to automate backups, fetch system stats, or launch a local web server, this tool saves you time. Because it relies heavily on proper directory structures and storage permissions, beginners sometimes run into setup hurdles. Let us clear those up right now.

Prerequisites Before You Begin

Before installing the widget, you need to make sure your base Termux environment is ready. If you downloaded Termux from the Google Play Store, stop right there. The Play Store version is deprecated and no longer receives updates. You should install Termux from F-Droid instead.

Open your terminal and run the following commands to update your package lists and grant storage access:

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

When the storage permission pop-up appears on your screen, tap Allow. This step is critical because the widget looks inside your shared storage directory for scripts to run.

Step-by-Step Installation Guide

Follow these exact steps to install Termux:Widget and configure your very first shortcut script.

Step 1: Install the Termux:Widget APK

Because of how Android handles app permissions and plugin communication, the widget app must be installed from the same source as your main Termux app. If you got Termux from F-Droid, download the Termux:Widget APK from F-Droid or the official GitHub releases page. Install the APK on your Android device.

Step 2: Create the Scripts Directory

Termux:Widget does not just read scripts from anywhere. It specifically looks inside a hidden folder located within your Termux home directory. Open your terminal and create the required directory by typing:

mkdir -p ~/.shortcuts

Step 3: Create a Test Script

Now, let us create a simple bash script that the widget can execute. We will make a script that updates your packages and displays a success message. Run this command in your terminal:

nano ~/.shortcuts/update.sh

Inside the nano text editor, paste the following lines:

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

Save the file by pressing Ctrl + O, hitting Enter, and then exiting with Ctrl + X. Next, make the script executable by running:

chmod +x ~/.shortcuts/update.sh

Step 4: Add the Widget to Your Home Screen

Go to your phone's home screen. Long-press on an empty space and tap on Widgets. Scroll through the list until you find the Termux section. You will see options for 1x1, 2x2, or differently sized widgets. Drag your preferred widget size onto your home screen.

A menu window will immediately pop up listing the scripts found in your ~/.shortcuts folder. Tap on update.sh. Your shortcut is now ready to use!

Example Terminal Output

When you tap your newly created home screen shortcut, Termux will launch in the background and execute your script. Your terminal output should look similar to this:

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

One of the most common issues users face is opening the widget configuration menu only to find it completely blank, or experiencing the dreaded termux widget shortcut not showing error. If your scripts refuse to appear, check these common fixes:

Common Cause	Why It Happens	How to Fix It
Wrong Directory	Scripts are placed in the home folder instead of the hidden shortcuts folder.	Ensure scripts reside in ~/.shortcuts/ (which expands to /data/data/com.termux/files/home/.shortcuts/).
Missing Permissions	Android is restricting background app execution or storage access.	Check Android App Settings for Termux:Widget and grant all requested permissions. Disable battery optimization for both Termux and the widget app.
Incorrect Shebang	The script lacks the proper interpreter path at the very top.	Add #!/data/data/com.termux/files/usr/bin/bash as the first line of your script.
Mixed Sources	Termux installed from F-Droid while the widget was downloaded from an incompatible source.	Ensure both Termux and Termux:Widget come from the exact same source (preferably F-Droid).

Expert Tips for Advanced Users

Want to get even more out of your terminal shortcuts? Try these expert strategies:

• Use Termux:Styling: Pair your shortcuts with custom color schemes inside Termux so your automated scripts look great when they pop open.
• Background Execution: If you want a script to run silently without opening the terminal window every time, append > /dev/null 2>&1 & to the end of your command inside the script.
• Icon Customization: Some custom Android launchers (like Nova Launcher) let you long-press the widget icon and change its image, making your terminal shortcuts look like native app icons.

Frequently Asked Questions

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

This usually happens because the script is not inside the ~/.shortcuts directory, or because the file lacks executable permissions. Run chmod +x ~/.shortcuts/your-script.sh to fix permission errors.

Can I run Python scripts using Termux:Widget?

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

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

No. Due to Android security sandboxing changes and the fact that the Play Store version is outdated, plugins cannot communicate properly with it. You must use the F-Droid versions of both apps.

What to Do Next

Now that your home screen is powered by custom terminal shortcuts, you can automate your mobile workflow completely. To take your setup a step further, check out our guide on how to write advanced automation scripts for Termux to build even more powerful background tasks.