Meta Description: Learn how to configure Termux file storage to access internal storage and SD cards. Fix the "termux ls storage/shared not found" error with our step-by-step commands and troubleshooting guide.

Termux Storage Guide: Access Internal & SD Card Files

By default, Termux lives in an isolated application sandbox. It cannot see your downloaded PDFs, your camera photos, or files resting on your external SD card until you explicitly grant it permission. Connecting Termux to your device's wider file system opens up powerful command-line capabilities—letting you automate file sorting, run Python scripts against local data, and manage media directly from a Linux shell.

In this guide, you will learn how to properly configure termux file storage, explore the internal symlink architecture, access external storage, and permanently resolve the common termux ls storage/shared not found error.

---

Quick Summary: How to Access Storage in Termux

To grant Termux access to your internal shared storage and create standard directory symlinks, execute the following command in your terminal:

termux-setup-storage

When the Android system dialog appears asking to "Allow Termux access photos, media and files on your device", tap Allow. Once granted, your shared storage becomes accessible at ~/storage/shared (which maps to /storage/emulated/0).

---

Understanding Termux File System Architecture

Termux does not follow the standard file hierarchy found on native Linux distributions like Ubuntu or Debian. Because Termux runs as an unprivileged Android application, its entire environment is installed inside its private app directory.

Here is how the storage environments differ:

• Termux Private Storage ($HOME or /data/data/com.termux/files/home): This is your default working directory when you launch the app. Other Android apps cannot read or modify files saved here unless your device is rooted.
• Android Shared Storage (/storage/emulated/0): This is your device's standard internal storage where Android stores folders like Download, DCIM, Documents, and Music. Termux cannot access this without user permission.
• External Storage (MicroSD / USB OTG): Physical SD cards and mounted storage drives located under /storage/XXXX-XXXX.

Running the built-in storage utility creates a special folder called ~/storage inside your Termux home directory. This folder contains symbolic links (shortcuts) pointing directly to key directories in your device's shared internal and external storage.

---

Step-by-Step: Enabling Storage Permissions in Termux

Follow these exact steps to connect Termux to your internal shared storage.

Step 1: Open Termux and Update Packages

Ensure your terminal session is active and your base environment is stable by opening Termux.

Step 2: Run the Storage Setup Utility

Type the following command and press Enter:

termux-setup-storage

Step 3: Grant System Permissions

A popup prompt will appear on your screen: "Allow Termux to access photos, media, and files on your device?" Tap Allow (or Allow management of all files depending on your Android version).

Step 4: Verify the Storage Symlinks

Confirm that the symlinks were created by listing the contents of the ~/storage directory:

ls -l ~/storage

You will see a list of symlinked directories pointing directly to standard Android user directories.

---

The ~/storage Directory Symlink Map

Executing termux-setup-storage automatically generates several symlinks inside $HOME/storage. Here is what each folder maps to on your physical device:

Symlink Path in Termux	Android Physical Location	Description / Purpose
~/storage/shared	/storage/emulated/0	The root directory of your internal shared storage.
~/storage/downloads	/storage/emulated/0/Download	Standard folder for browser and system downloads.
~/storage/dcim	/storage/emulated/0/DCIM	Camera photos and captured videos.
~/storage/pictures	/storage/emulated/0/Pictures	Screenshots, wallpapers, and image editor exports.
~/storage/music	/storage/emulated/0/Music	Locally stored audio and music tracks.
~/storage/movies	/storage/emulated/0/Movies	Video files, recordings, and media clips.
~/storage/external-1	/storage/XXXX-XXXX/Android/data/com.termux/files	App-private directory on your physical MicroSD card (if inserted).

---

Fixing the "termux ls storage/shared not found" Error

One of the most frequent errors encountered by new users is:

ls: cannot access 'storage/shared': No such file or directory

or

termux ls storage/shared not found

This issue occurs due to one of three specific causes. Work through these troubleshooting steps to resolve it.

Cause 1: Relative Path Mismatch (Most Common)

If you type ls storage/shared while your current working directory is not your home directory (~), Termux looks for a folder called storage/shared relative to where you currently stand. If you navigated to another folder (like /data/data/com.termux/files/usr), the relative path fails.

The Fix: Always use the tilde (~) or the full absolute environment variable ($HOME) when referencing storage symlinks:

ls ~/storage/shared

or

ls $HOME/storage/shared

Cause 2: termux-setup-storage Was Never Executed

Termux does not generate the ~/storage directory out of the box. If you try to list ~/storage/shared on a fresh install before configuring permissions, the terminal will return a "not found" error.

The Fix: Run the initialization command:

termux-setup-storage

Wait a couple of seconds, grant the permission prompt, and list the directory again.

Cause 3: Android Permission Was Denied or Revoked

If permission was accidentally denied or later revoked by Android's automated permission manager, the symlink will remain broken.

The Fix:

1. Open your device's Settings app.
2. Navigate to Apps > Termux > Permissions.
3. Ensure Files and media (or Storage) is set to Allow / Allow management of all files.
4. Return to Termux, run termux-setup-storage once more, and verify with ls ~/storage/shared.

---

How to Move and Manage Files Between Termux and Internal Storage

Once storage access is established, you can use standard Linux commands to manage files across both file systems.

1. Listing Files in Internal Storage

View all folders in your phone's main internal storage:

ls -lh ~/storage/shared

View files in your standard Downloads directory:

ls -lh ~/storage/downloads

2. Copying Files into Termux Home

If you downloaded a script named backup.py using your mobile browser and want to edit it inside Termux's private home environment, copy it using cp:

cp ~/storage/downloads/backup.py ~/backup.py

3. Moving Files from Termux to Internal Storage

If you generated an output file (such as a compressed archive project.zip) inside Termux and want to send it to a friend via WhatsApp or email, move it to your Downloads folder so standard Android apps can access it:

mv ~/project.zip ~/storage/downloads/

4. Creating Folders in Shared Storage

Create a dedicated workspace folder inside your phone's internal storage:

mkdir -p ~/storage/shared/TermuxWorkspace

---

Accessing MicroSD Cards and USB OTG Flash Drives

Handling external media requires understanding how Android manages removable storage permissions.

MicroSD Card Access

When you run termux-setup-storage with a MicroSD card inserted, Termux automatically creates a symlink named ~/storage/external-1. This points directly to the app-private folder on your physical card: /storage/XXXX-XXXX/Android/data/com.termux/files.

Termux has full read and write access inside this specific private folder. Writing to the arbitrary root of an external SD card is restricted by Android's security framework on non-rooted devices.

USB OTG Flash Drives

For external USB OTG flash drives, Android mounts them with strict access policies. If Termux cannot directly write to the OTG drive path, use this reliable two-step staging workflow:

1. Open your Android device's native Files app.
2. Copy or move the files from your USB OTG drive into your device's internal storage (e.g., inside /storage/emulated/0/Download).
3. Switch to Termux and access the files seamlessly via ~/storage/downloads/.
4. To write data back to the USB drive, save your output to ~/storage/downloads/ first, then use the Android Files app to transfer the finished files onto the OTG drive.

---

Best Practices and Common Mistakes

• Handle Spaces in File and Folder Names: Android folders often contain spaces (e.g., My Documents). In the terminal, either wrap the path in quotes or escape the space with a backslash:

  cd ~/storage/shared/"My Documents"
  cd ~/storage/shared/My\ Documents

• Remember Linux is Case-Sensitive: While some Android file systems are case-insensitive, Termux treats paths strictly. ~/storage/downloads is not the same as ~/storage/Downloads. Always use the lowercase symlink names provided in ~/storage.
• Keep Heavy Builds in $HOME: Compiling large codebases, installing complex Python packages, or building Node.js projects runs significantly faster inside Termux's native private directory ($HOME) than on shared storage (/storage/emulated/0) due to Android's storage virtualization overhead.
• Avoid Modifying Android System Directories: Stick to standard user directories (shared, downloads, dcim). Modifying system-level Android folders can corrupt app cache data.

---

Frequently Asked Questions (FAQ)

What does termux-setup-storage actually do?

It performs two key actions: first, it triggers Android's runtime permission dialog asking you to grant Termux storage permissions; second, it creates the ~/storage folder populated with convenient symbolic links pointing to common internal and external storage paths.

Can other Android apps view files in my Termux home folder?

No. Termux's private home directory (/data/data/com.termux/files/home) is sandboxed by Android security rules. Other apps cannot view or edit these files unless you move them to shared storage (like ~/storage/shared or ~/storage/downloads).

Why do I get "Permission denied" even after running termux-setup-storage?

On modern Android versions (Android 11 and newer), you may need to grant All files access. Check your device Settings under Apps > Special app access > All files access > Termux and make sure the toggle is enabled.

How do I remove or reset the storage setup?

If you want to remove the symlink shortcuts, you can safely delete the ~/storage directory by running rm -rf ~/storage. This removes only the symbolic links inside Termux; it does not delete your actual personal files on internal storage.

---

What to Do Next

Now that your storage permissions are configured and you can freely move files between Termux and internal memory, you are ready to expand your command-line workspace. Check out our comprehensive guide on essential Termux commands and Linux package setup to master file management, package installations, and terminal customization.