Termux Genius

Home

How to Fix Termux Black Screen or Crash Issue

A black screen, an instant crash on launch, or a session that dies the moment you lock your phone — these are three different problems that get lumped together under one complaint: "Termux keeps crashing." The fix depends entirely on which one you actually have, and on which Android version you're running. This guide starts by narrowing that down, then walks through the exact steps for each cause, including the Android 16 startup crash that surfaced in March 2026.

Before touching anything, back up your data. Several of these fixes involve reinstalling or clearing app data, and Android will not warn you before it wipes your Termux home directory.

Quick Diagnostic Checklist

Answer these questions first — they point straight to the right section:

  • What Android version are you on? (Settings → About phone). Android 14, 15, and 16 have a one-tap fix; Android 12 and 13 need a computer.
  • Did you install Termux from the Play Store or from F-Droid/GitHub? The Play Store build is outdated and causes crashes on its own.
  • Is the screen black immediately on open, or does it die later — after locking the phone or switching apps? Immediate black screen usually means a broken shell config file; dying later almost always means Android is killing the background process.
  • Is this the main Termux app, or Termux:X11? X11 (the GUI/desktop add-on) has a separate, unrelated set of black-screen causes.
  • Did the crash start right after an Android or Termux update? If yes, jump to the version-specific fixes below.

Back Up Your Termux Data First

Several fixes below involve clearing app data or reinstalling. Do this first, every time:

# Back up your home directory to shared storage
tar -czvf ~/storage/shared/termux-backup-$(date +%Y%m%d).tar.gz ~

# Save your installed package list so you can restore it later
pkg list-installed > ~/storage/shared/installed-packages.txt

# Back up SSH keys separately if you use them
cp -r ~/.ssh ~/storage/shared/ssh-backup

If you haven't run termux-setup-storage yet, that command needs to succeed before the backup will work — it's what gives Termux permission to write to ~/storage/shared.

Fix #1: Confirm You're Running the Official Build (F-Droid or GitHub)

Termux's Google Play release has not received the last several years of updates and fixes; the maintainers officially recommend installing only from F-Droid or the project's GitHub releases page. Play Store users have reported reinstalling entirely different, older builds that reintroduce fixed bugs — so if your crashes started after a Play Store update, this is very likely why.

FeatureF-Droid / GitHubPlay Store
Actively maintainedYesNo — years behind
Compatible with current Android security modelYesPartial, inconsistent
Officially recommended by Termux developersYesNo

To check which build you have, run:

termux-info

Look at the TERMUX_VERSION line. If you're on the Play Store build, back up first, then uninstall it and install from F-Droid instead — the two builds use different signing keys, so one cannot update over the other; a clean uninstall/install is required.

Fix #2: Termux Dies in the Background (Phantom Process Killer)

If Termux stays open fine but any background job — an SSH session, a local server, a long-running script — dies the moment you lock the screen or switch apps, this is Android's phantom process killer, a feature Google added starting with Android 12 that force-kills background child processes once a count limit is hit. It isn't a Termux bug; it's the same behavior other terminal and dev-tool apps run into. The fix depends entirely on your Android version.

Android 14, 15, or 16: Developer Options Toggle (2 minutes, no computer)

  1. Go to Settings → About phone, then tap Build number seven times to unlock Developer Options.
  2. Go to Settings → System → Developer Options.
  3. Find "Disable child process restrictions" and turn it on.
  4. Reboot your device.

This setting is the direct successor to the ADB flag below — Google exposed it in the UI starting with Android 14 so users no longer need a computer.

Android 12, 12L, or 13: ADB Command (needs a computer)

This toggle doesn't exist in Settings on Android 12/13, so it has to be set via ADB. Enable USB debugging in Developer Options, connect your phone to a computer with ADB installed, then run:

adb shell settings put global settings_enable_monitor_phantom_procs false

On Android 12 specifically, some devices also need:

adb shell "/system/bin/device_config set_sync_disabled_for_tests persistent"
adb shell "/system/bin/device_config put activity_manager max_phantom_processes 2147483647"

Reboot afterward. Note that on Android ≥14, this same setting reverts automatically if Developer Options gets turned off — the Settings toggle above is the more durable option once it's available on your device.

If you're also running background automation, pair this with termux-wake-lock to stop the CPU from sleeping mid-script — worth combining with the battery settings in the next section.

Fix #3: Set Battery Usage to Unrestricted

Separately from the phantom process killer, Android's per-app battery optimization can also suspend Termux. Go to Settings → Apps → Termux → Battery, and change it from "Optimized" or "Restricted" to Unrestricted. On heavily customized OEM software (HyperOS, One UI, OxygenOS, ColorOS, and similar), there is usually a second, separate toggle — often under a "manage apps" or "autostart" screen rather than the battery menu itself — so check both the standard Android battery settings and your manufacturer's own app-management screen. If you use Termux:API alongside the main app, make sure that companion app is updated too, since a version mismatch between Termux and its plugins is a separate, common source of crashes.

Fix #4: Android 16 Startup Crash (Permission Denied)

In March 2026, a batch of Android 16 users reported that Termux 0.118.3, installed fresh via F-Droid, crashed immediately on startup with a permission-denied error touching Termux's internal files — documented in termux-app issue #5032 on Pixel 6 hardware. If you're on Android 16 and hit this:

  1. Reboot the device. A number of affected users report this alone resolves the startup crash, likely because it clears a stale internal state left over from the fresh install.
  2. If it still crashes, update to Termux 0.119.0-beta.3 or newer from the official GitHub releases page. This release specifically bumps a compatibility library to fix a crash on Android 16 QPR1 devices, installing over your current version without erasing your data.
  3. Reboot again after installing.

This is a young, actively-tracked issue — if these steps don't resolve it for your specific device, that's worth reporting rather than assuming you've done something wrong (see the reporting section near the end).

Fix #5: Should You Use the Beta Version?

Termux's stable channel (0.118.x) is what most people should stay on. Switch to the 0.119.0-beta series only if:

  • You're on Android 16 and hitting the startup crash above, where the beta contains a specific fix stable doesn't have yet.
  • A GitHub issue for your exact symptom explicitly says the beta resolves it.

Stay on stable if Termux is currently working, or if you rely on it for uninterrupted daily work — betas can carry other unpatched bugs. To install a beta, download the matching .apk variant for your device architecture from the GitHub releases page (not F-Droid, which tracks stable), and install it over your current app; your data is preserved.

Fix #6: Immediate Black Screen — Broken Shell Configuration

If the black screen appears the instant you open Termux, before you can type anything, the most common cause is a syntax error in a shell startup file — usually .bashrc or .profile — introduced while editing environment variables or aliases. The shell crashes while trying to read that file, before it ever draws a prompt.

  1. Force-stop Termux from Android's app settings.
  2. Reopen it. If you can get any input at all, long-press the screen, choose More, and look for a session-reset option.
  3. If you get a working prompt, rename the suspect files rather than deleting them, so you can inspect what broke:
cd ~
mv .bashrc .bashrc.bak
mv .profile .profile.bak

If no prompt appears at all, Clearing App Data (Settings → Apps → Termux → Storage → Clear Data) will get you a working shell again, but it wipes your entire home directory — only do this once you've confirmed a backup exists. For a deeper look at safely writing and testing shell scripts so this doesn't recur, see our guide on creating and running Bash scripts in Termux.

Fix #7: Crashes During Package Updates or Broken Repositories

If the crash happens specifically while running pkg update or installing a package, the issue is usually a broken or overloaded repository mirror rather than the app itself:

termux-change-repo
pkg update -y
pkg upgrade -y

When the mirror-selection prompt appears, pick a stable, well-known mirror rather than leaving it on an overloaded default. If a previous install was interrupted mid-way (for example, by force-stopping Termux during pkg upgrade), you may also need:

dpkg --configure -a
apt clean
pkg update

If you're regularly hitting "unable to locate package" alongside these crashes, that's a distinct, related issue — our guide on fixing "unable to locate package" errors covers it in more depth. For the full weekly maintenance routine that helps prevent this from recurring, see updating and upgrading packages in Termux.

Fix #8: Storage Permission Crashes

If your crash happens specifically when a script tries to read or write shared storage (photos, downloads, external files), Termux needs its runtime storage permission granted, and it needs to be re-granted after certain Android storage-model updates:

termux-setup-storage

Approve the permission prompt when it appears. If this doesn't resolve access errors, our dedicated Termux storage permission fix guide walks through the less obvious cases, including revoked permissions after an OS update.

Fix #9: Is It Termux:X11, Not the Main App?

Termux:X11 is a separate companion app that runs a graphical desktop environment on top of Termux — and it has its own, unrelated black-screen problem, most often reported when reopening the X11 app after closing it, or when an XFCE4 desktop fails to redraw. If you're troubleshooting a GUI/desktop session rather than the plain terminal:

  • Force-stopping doesn't fully kill the X server — instead run pkill Xtermux or restart it explicitly with termux-x11 :0 &.
  • Make sure DISPLAY is set: export DISPLAY=:0.
  • Set the display resolution to "native" or "scaled" rather than a custom/exact value, which is a frequent trigger for the black screen in XFCE4 sessions.

Applying the phantom-process or battery fixes above won't help an X11-specific black screen, and vice versa — confirm which app is actually crashing before you spend time on either path.

Last Resort: Reinstalling Safely

If none of the above resolves it, and you've confirmed a backup exists:

  1. Settings → Apps → Termux → Storage → Clear Data (this keeps the app installed but resets the environment — try this before a full uninstall).
  2. Reopen Termux and let it reinstall its base packages.
  3. Restore your backed-up files and reinstall packages from your saved list.

Only fall back to a full uninstall/reinstall from the F-Droid build if Clear Data doesn't fix it.

If Nothing Here Fixes It: Reporting the Bug

Termux's crash landscape shifts with every Android release, so if your specific symptom isn't covered above, it may be a newly emerging issue. Before reporting, confirm you're on the official F-Droid/GitHub build, and capture a log if you can — installing a basic terminal app and running logcat | grep -i termux while reproducing the crash is usually enough. Report to the termux-app GitHub issues page with your Termux version, Android version, device model, and the relevant log lines.

FAQs

Why does Termux show a black screen on startup?

Most often a broken shell startup file (.bashrc or .profile), a Play Store build issue, or — on Android 16 — a known permission-denied crash on fresh installs. Check the diagnostic checklist above to identify which applies to you.

Will reinstalling Termux delete my files?

Yes, if you uninstall without backing up first. Clearing app data also wipes your home directory. Always run the backup commands in this guide before either action.

What's the difference between Termux and Termux:X11?

Termux is the terminal emulator itself. Termux:X11 is a separate app that adds a graphical desktop on top of it. Black screens in each have different causes and different fixes — see the X11 section above.

Should I use the beta version of Termux?

Only if you're on Android 16 hitting the specific startup crash covered above, or a GitHub issue confirms the beta fixes your exact symptom. Otherwise, stay on the stable F-Droid release.

How do I know if the phantom process killer is affecting Termux?

If a background job survives while the app is open but dies the moment you lock the phone or switch away, that's the signature symptom. Run a long sleep command, switch apps for a minute, and check if it's still running when you return.

Conclusion

Most Termux crashes trace back to one of a handful of causes: an outdated Play Store build, Android's background process limits, a broken config file, or — on Android 16 right now — a known startup bug with a beta-version fix. Back up before you touch anything, match the fix to your actual Android version, and escalate to GitHub if your case genuinely isn't covered here.