Termux Storage Guide: Access Internal & SD Card Files

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

In this guide, you'll learn how to properly configure Termux file storage, understand its internal symlink structure, access external SD cards, and resolve the common ls: cannot access 'storage/shared': No such file or directory error.

Quick Summary: How to Access Storage in Termux

To grant Termux access to your internal shared storage and create standard directory symlinks, run:

termux-setup-storage

When the Android permission dialog appears asking to allow Termux access to photos, media, and files, tap Allow. Once granted, your shared storage becomes accessible at ~/storage/shared, which maps to /storage/emulated/0.

Understanding Termux File System Architecture

Termux doesn't follow the standard file hierarchy found on a native Linux distribution like Ubuntu or Debian. Because it runs as an unprivileged Android app, its entire environment lives inside its own private app directory. If you're new to Termux generally, our guide on how to install Termux on Android is a good starting point.

Here's how the storage environments differ:

• Termux private storage ($HOME, i.e. /data/data/com.termux/files/home): your default working directory when you open the app. Other apps can't read or modify files here unless the device is rooted.
• Android shared storage (/storage/emulated/0): your device's standard internal storage, holding folders like Download, DCIM, Documents, and Music. Termux can't access this without permission.
• External storage (MicroSD / USB OTG): physical cards and mounted drives, found under paths like /storage/XXXX-XXXX.

Running the storage setup utility creates a special folder called ~/storage inside your Termux home directory, containing symbolic links that point directly to key folders on your device's internal and external storage.

Step-by-Step: Enabling Storage Permissions in Termux

Step 1: Open Termux

Make sure your terminal session is active. New to the terminal itself? Our basic Termux commands for beginners guide covers the essentials.

Step 2: Run the Storage Setup Utility

Type the following and press Enter:

termux-setup-storage

Step 3: Grant System Permissions

A prompt will appear asking whether to allow Termux to access photos, media, and files on your device (wording varies slightly by Android version). Tap Allow.

Once granted, listing your storage folder shows the created symlinks:

$ termux-setup-storage
$ ls -la ~/storage
dcim -> /storage/emulated/0/DCIM
downloads -> /storage/emulated/0/Download
movies -> /storage/emulated/0/Movies
music -> /storage/emulated/0/Music
pictures -> /storage/emulated/0/Pictures
shared -> /storage/emulated/0

Step 4: Verify the Storage Symlinks

Confirm the symlinks were created:

ls -l ~/storage

You should see a list of symlinked directories pointing to standard Android folders.

The ~/storage Directory Symlink Map

Running termux-setup-storage generates several symlinks inside $HOME/storage. Here's what each one points to:

Fixing the "storage/shared not found" Error

One of the most common errors new users hit is:

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

This has one of three specific causes. Work through them in order.

Cause 1: Relative Path Mismatch (Most Common)

If you type ls storage/shared while your current directory isn't your home directory (~), Termux looks for a folder called storage/shared relative to wherever you currently are. If you've navigated elsewhere — say, into /data/data/com.termux/files/usr — the relative path fails.

Fix: Always reference storage with the tilde or $HOME:

ls ~/storage/shared

or

ls $HOME/storage/shared

Cause 2: termux-setup-storage Was Never Run

Termux doesn't generate ~/storage automatically. On a fresh install, listing it before running the setup command will return a "not found" error.

Fix: Run the initialization command, then wait a couple of seconds and grant the permission prompt:

termux-setup-storage

Cause 3: Android Permission Was Denied or Revoked

If permission was denied initially, or later revoked by Android's automatic permission manager, the symlinks stop working.

Fix:

1. Open your device's Settings app.
2. Go to Apps > Termux > Permissions.
3. Make sure Files and Media (or Storage) is set to Allow.
4. Return to Termux, run termux-setup-storage again, and verify with ls ~/storage/shared.

Moving and Managing Files Between Termux and Internal Storage

Once storage access is set up, standard Linux commands work across both file systems.

Listing Files in Internal Storage

ls -lh ~/storage/shared
ls -lh ~/storage/downloads

Copying a File Into Termux's Home Directory

If you downloaded a script named backup.py through your mobile browser and want to edit it inside Termux — see our guide on installing Python in Termux if you haven't set that up yet — copy it with cp:

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

Moving a File From Termux to Internal Storage

If you generated an output file inside Termux (say, a compressed archive) and want to share it through a normal Android app, move it to your Downloads folder first:

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

Creating Folders in Shared Storage

mkdir -p ~/storage/shared/TermuxWorkspace

Accessing MicroSD Cards and USB OTG Flash Drives

MicroSD Card Access

With a MicroSD card inserted, termux-setup-storage creates a symlink named ~/storage/external-1, pointing to an app-private folder on the card: /storage/XXXX-XXXX/Android/data/com.termux/files. Termux has full read/write access inside this specific folder, but writing to the arbitrary root of the SD card is restricted by Android's storage permissions on non-rooted devices — that's an Android platform restriction, not a Termux limitation.

USB OTG Flash Drives

Android applies strict access policies to USB OTG drives. If Termux can't write to the drive directly, use this staging workflow instead:

1. Open your device's native Files app.
2. Copy the files from your OTG drive into internal storage (e.g. /storage/emulated/0/Download).
3. Access them from Termux via ~/storage/downloads/.
4. To write data back, save your output to ~/storage/downloads/ first, then use the Files app to move it 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). Quote the path or escape the space: cd ~/storage/shared/"My Documents" or cd ~/storage/shared/My\ Documents.
• Remember Linux is case-sensitive. Even though some Android file systems aren't, Termux treats paths strictly — ~/storage/downloads is not the same as ~/storage/Downloads. Stick to the lowercase names Termux generates.
• Keep heavy builds inside $HOME. Compiling large codebases or installing big packages runs noticeably faster inside Termux's private directory than on shared storage, due to Android's storage virtualization overhead.
• Avoid modifying Android system directories. Stick to standard user folders (shared, downloads, dcim, etc.) rather than system-level paths.

Frequently Asked Questions

What does termux-setup-storage actually do?

It does two things: triggers Android's runtime permission dialog asking you to grant Termux storage access, and creates the ~/storage folder populated with symbolic links to common internal and external storage paths.

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

No. Termux's private home directory is sandboxed by Android security rules. Other apps can't view or edit those files unless you move them into shared storage (~/storage/shared or ~/storage/downloads).

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

First, re-run termux-setup-storage and confirm you tapped Allow on the prompt, then check Settings > Apps > Termux > Permissions to make sure Files and Media (or Storage) access is enabled. On some Android versions, if standard access still doesn't resolve it, you can additionally check Settings > Apps > Special app access > All files access > Termux — though most users only need the standard permission grant.

How do I remove or reset the storage setup?

Delete the ~/storage directory with rm -rf ~/storage. This only removes the symbolic links inside Termux — it does not delete your actual files on internal storage.

What to Do Next

With storage access configured, you're ready to put it to use — try downloading YouTube videos using Termux or converting video files with FFmpeg in Termux, both of which rely directly on the storage paths covered in this guide. If you're also using Termux:API for device features, our comparison of Termux vs. Termux:API explains how the two fit together.