Troubleshooting & FAQ
Relevant source files
The following files were used as context for generating this wiki page:
This documentation provides solutions for common issues encountered when running Linux Desktop Environments (DE) on Android via Termux. It covers session management, display configuration, hardware acceleration conflicts, and input device optimization across Native, PRoot, and Chroot environments.
Session and Process Management
A frequent issue in Termux environments is the Android OS killing long-running background processes, specifically the Termux:X11 session.
Termux:X11 Randomly Shutdown
Android's "Phantom Process Killer" often terminates Termux sessions. Users must disable this feature to ensure stability. Even after disabling it, specific battery optimization settings may still interfere.
To manually ensure a clean shutdown of a stuck session, use the following command:
kill -9 $(pgrep -f "termux.x11") 2>/dev/null
Sources: Documentation/native/termux_native.md:213-228, Documentation/native/termux_native.md:231-236
Chroot Safety Warning
When using Chroot environments, users must close the Termux application completely (including background) before attempting to delete chroot folders. Failure to do so while mounts are active can lead to system instability requiring a force reboot.
Sources: Documentation/chroot/debian_chroot.md:1-5, Documentation/chroot/arch_chroot.md:1-5
Display and Resolution Issues
Resolution and Scaling
Issues where the resolution is too large, too small, or scaling makes UI elements unreadable can be adjusted through Termux:X11 preferences.
| Issue | Workaround/Fix |
|---|---|
| Incorrect Resolution | Press the Android back key or go home and return to the app. |
| UI/Icons too small | Stop session -> Preferences -> Change resolution mode to Scaled -> Adjust Display Scale %. |
| Cursor Speed | Preferences -> Adjust Captured pointer speed factor. |
| Cursor Capture | Enable Capture external pointer devices when possible. |
Sources: Documentation/native/termux_native.md:243-255
Hardware Acceleration Troubleshooting
Hardware acceleration (GLA) significantly improves performance but introduces complexity depending on the GPU architecture (Adreno vs. Mali vs. PowerVR).
Graphics Drivers Comparison
| Driver | GPU Compatibility | Description |
|---|---|---|
| Zink + Turnip | Adreno 610+ | Best hardware acceleration. Translates OpenGL to Vulkan. |
| Freedreno | Adreno | Open-source OpenGL driver. |
| VirGL | Most GPUs | Virtual OpenGL renderer; generally lower performance. |
| LLVMpipe | Universal | Software rasterizer (CPU-based); slowest performance. |
Sources: Documentation/terminology.md:46-86, Documentation/terminology.md:111-120
Black Screen on Archlinux (Turnip)
In Archlinux PRoot/Chroot environments, Turnip drivers may cause a black screen if the XFCE4 compositor is enabled.
- Resolution: Disable the compositor in
Settings -> Window Manager Tweaks -> Compositor. - Recovery: If already at a black screen, enter chroot as root and remove the loader:
pacman -R vulkan-icd-loader. Reinstall after disabling the compositor.
Sources: Documentation/HardwareAcceleration.md:195-208
Input and Keyboard Fixes
WASD / QWERTY Keys Not Registering
Games often fail to register standard movement keys. This is typically caused by how Android handles key events.
- Fix: In Termux:X11 Preferences, toggle Prefer scancodes when possible.
- Alternative: Hold
CTRLwhile pressing the keys as a temporary workaround.
Sources: Documentation/HardwareAcceleration.md:255-261
Mobox and Windows Emulation FAQ
Running Windows programs via Mobox within a Termux Desktop requires specific environment handling.
Directory Execution Issues
Many Windows executables require the terminal to be in the same directory as the .exe.
Resolution Changes in Games
Older games often attempt to resize the screen resolution, which Mobox/Termux:X11 cannot handle dynamically.
- Solution: Run the program within a virtual wine desktop:
wine explorer /desktop=true PROGRAM.exe
Sources: Documentation/native/termux_native.md:144-149
Wine Staging vs. Vanilla
Compatibility varies by application (e.g., Undertale requires Wine Staging to avoid Direct3D errors). Users can switch versions within Mobox settings: mobox -> 3. Manage Packages -> 2. Install wine.
Sources: Documentation/native/termux_native.md:156-173
Summary
Troubleshooting in Termux Desktops primarily involves managing Android's aggressive process management, selecting the correct graphics driver for the device's GPU, and ensuring input settings are optimized for desktop-style interactions. Stability is best achieved by disabling Android's phantom process killer and properly configuring Termux:X11 preferences before starting sessions.