LinuxOnVita - Complete Handheld Linux Distribution for PS Vita

A complete distribution, automated build environment, and handheld userland for running Linux 6.12 on hacked PlayStation Vita consoles (HENlo / HENkaku / Ensō 3.60 & 3.65).

While original proof-of-concept projects proved that modern Linux can boot on the PS Vita SoC, they required specialized developer equipment such as soldered UART serial cables. LinuxOnVita bridges the gap into a fully standalone, interactive handheld Linux device with out-of-the-box touch typing, physical gamepad navigation, automated on-device Wi-Fi, memory-safe ZRAM swap, full package management (apk), and native framebuffer gaming.

_{Lightweight IceWM Graphical Desktop & Handheld Welcome Guide (alpine-desktop)}

Interactive Welcome Screen & Touch Keyboard	Native Framebuffer DOOM (Full Screen 960x544)
Fastfetch & Package Management in Alpine Linux	Interactive On-Device Wi-Fi Manager (vita-wifi)

• Built-in Touch Keyboard (fbkeyboard): Type directly on the console screen with an on-framebuffer virtual keyboard featuring dual ABC / ?123 layouts, special keys, and a hide toggle.
• Physical Gamepad Navigation (vita-input-mapper): Complete console shell navigation using the D-Pad, face buttons, and shoulder triggers synthesized through /dev/uinput.
• Fixed Controller Logic: Corrected inverted button mask issues and initialized analog sticks via Syscon for smooth twin-stick controls in games and terminal navigation.
• Full Display Brightness: Patched baremetal bootloaders to initialize displays at 100% brightness on both OLED and LCD models, plus runtime backlight adjustment on PS Vita 2000 via vita-brightness.
• Interactive On-Device Wi-Fi Manager (vita-wifi): Scan, connect, and switch wireless networks directly on the console with an ASCII signal table. Saves credentials permanently to your memory card without needing to edit config files on a PC.
• Fast Boot & OpenSSH: Boots straight into the Linux terminal. Wi-Fi connects automatically with OpenSSH and mDNS (vita.local), ready in ~12 seconds.
• Alpine Linux Chroot (alpine-chroot): Run an isolated, persistent Alpine Linux userland on storage with full apk add package management.
• Compressed ZRAM & Memory Safety (vita-swap): Zero-latency LZ4 compressed RAM swap expands usable memory from 512MB to ~768MB-1GB, preventing Out-Of-Memory (OOM) crashes during heavy package installs, Python scripts, or C compilation. Includes physical SD card swapfile auto-mounting.
• Storage Auto-Mounting: Automatically detects and mounts SD2Vita (/mnt/ux0), internal memory (/mnt/ur0), and secondary storage (/mnt/uma0) on boot.
• Framebuffer DOOM (vita-doom): Pre-installed pure-C fbdoom engine with twin-stick controls, analog deadzones, and input isolation.
• All-in-One Installer App (LinuxOnVita.vpk): Graphical bootstrapper with real-time partition detection, memory card mount selector, and 1-click on-device installer.
• Automated Docker Build: Build the entire stack (kernel, rootfs, loaders, and VPK) with a single command (./build.sh all).

1. Custom Firmware: Any PS Vita (1000 OLED, 2000 Slim, or PlayStation TV) running 3.60 or 3.65 with HENkaku / Ensō (see vita.hacks.guide).
2. Enable Unsafe Homebrew (Critical):
   • Open Settings -> HENkaku Settings -> check Enable Unsafe Homebrew [✓]. If unchecked, the loader plugin will fail with error 0x8002D003.
3. Official Sony Memory Card Strictly Required:
   • The baremetal loader interfaces directly with Sony's proprietary memory card hardware (MSIF). It cannot boot from SD2Vita game-card adapters or internal eMMC (imc0:).
   • SD2Vita Users: Your SD2Vita adapter mounts as ux0:, and your official Sony card is typically xmc0: or uma0:. The LinuxOnVita app automatically detects your Sony card and installs boot files directly to it.

1. Download LinuxOnVita.vpk from the GitHub Releases page.
2. Transfer LinuxOnVita.vpk to your PS Vita using VitaShell (USB or FTP).
3. In VitaShell, highlight LinuxOnVita.vpk and press CROSS (✕) to install. You can install it to any partition (ux0:, uma0:, etc.) - it does not matter where the app itself lives.
4. Launch LinuxOnVita from the LiveArea.
5. Select your Sony Memory Card partition (e.g. xmc0: or uma0: for SD2Vita users, ux0: for standard consoles) and press CROSS (✕) to install the bundled Linux boot files to it.
6. Press CROSS (✕) to boot straight into Linux!

For full usage instructions, gamepad shortcuts, and Wi-Fi setup, see the Complete User Guide.

You can build the entire distribution (RootFS, Linux 6.12 Kernel, baremetal loaders, and the VPK) using Docker:

git clone https://github.com/devwithzachary/LinuxOnVita.git
cd LinuxOnVita

# Build the Docker build environment container (one-time setup)
./build.sh image

# Build everything: RootFS, Kernel, Loaders, and LinuxOnVita.vpk
./build.sh all

# (Optional) Package a complete release archive
./build.sh release

All compiled outputs are saved to output/:

• output/LinuxOnVita.vpk: The all-in-one bootstrapper and installer.
• output/ux0/linux/: Standalone boot files (zImage, vita1000.dtb, vita2000.dtb, payload.bin, baremetal-loader.skprx).
• output/LinuxOnVita-release-<version>.zip: Distributable all-in-one release archive.

• Error 0x8002D003 when launching LinuxOnVita: Unsafe Homebrew is disabled. On your Vita, go to Settings -> HENkaku Settings -> check Enable Unsafe Homebrew.
• "Memory card not inserted" on boot: An official Sony memory card is strictly required on all consoles (both 1000 and 2000 models). The baremetal bootloader only speaks to Sony MSIF hardware and cannot read from internal eMMC or SD2Vita adapters.
• Frozen on Uncompressing Linux... done, booting the kernel: The Device Tree blob does not match your hardware. In LinuxOnVita, reinstall boot files or ensure vita1000.dtb (OLED) or vita2000.dtb (LCD) is copied to your memory card's linux/vita.dtb.
• Boot loop when returning to VitaOS after running Linux: This is caused by a USB streaming or storage remapping kernel plugin (e.g. VitaUSBStream, YAMT, StorageMgr) conflicting with hardware state left by the baremetal loader. To recover: hold L trigger on power-on to bypass plugins, then open VitaShell, edit ur0:tai/config.txt (or ux0:tai/config.txt), and comment out or remove the offending *KERNEL* plugin entry. See the compatibility warning above for the full explanation.

For additional help and step-by-step guidance, see the Complete User Guide.

This project builds upon the groundbreaking research and development of the PS Vita homebrew and Linux reverse-engineering community:

• incognitojam:
  • vita-linux-port - Modern Linux 6.12 port, Marvell Wi-Fi custom power sequencing (pwrseq_vita_wlan.c), High-Res timer fix, SCE eMMC partition driver, and Buildroot integration.
  • linux_vita (6.12) - Modernized Linux 6.12 kernel tree for PS Vita.
• xerpi (Sergi Granell):
  • Original Linux on PS Vita pioneer: linux_vita, vita-baremetal-loader, vita-libbaremetal.
• DvaMishkiLapa:
  • vita_plugin_linux_loader - Bootstrapper VPK with partition file verification.
• Team Molecule & taiHEN - HENkaku jailbreak and taiHEN kernel framework.
• VitaSDK - Open-source PlayStation Vita software development kit.
• Bootlin - Precompiled ARMv7 cross-compilation toolchains.

Have questions, need help troubleshooting, or want to share photos and clips of Linux running on your Vita? Join our Discord Community!

Contributions, bug reports, and feature requests are welcome! Feel free to join the discussion on Discord, check out the issues page, or submit a pull request.

Please review our AI Usage Policy for guidelines on using AI coding assistants when contributing to this project. All code submitted must be thoroughly reviewed and personally owned by the human author; automated bot PRs are not accepted.

If LinuxOnVita has been useful to you, consider supporting continued development:

 

LinuxOnVita is licensed under the GNU General Public License v3.0 (GPL-3.0). Upstream source trees (Linux kernel, Buildroot, VitaSDK) retain their respective licenses (GPLv2, MIT, BSD).