BlueStacks Root GUI

---

A utility to toggle root access and read/write (R/W) permissions for BlueStacks 5 instances from a simple graphical interface. It automates the process described in Root BlueStacks with Kitsune Mask.

Tip

The latest BlueStacks now roots — no downgrade required. BlueStacks 5.22 added a disk-integrity check that shut rooted instances down with "Android system doesn't meet security requirements". This tool patches that check out, so you can root the current build instead of hunting for an old one. Confirmed working on 5.22.232.1002 / Android 13 — the current latest official BlueStacks build as of July 2026 (see Version Compatibility). If you were told to downgrade to 5.21, you no longer have to.

---

Table of Contents

• Features
• How It Works
• Prerequisites
• Installation
• Usage Guide
  • Patch-Mode Builds (5.22.150.1014+)
  • Classic Builds (5.22.130 and older / MSI)
  • Keep Root After Updates
• Troubleshooting
• Development
• Contributing

---

Features

• Auto-Detection - Discovers BlueStacks installation paths via the Windows Registry (Normal, China, and MSI editions) and picks the right rooting method per version automatically
• Instance Listing - Lists every instance with live Root and R/W status, including newer instances that use a single Data.vhdx layout (created or cloned) — not just the classic fastboot.vdi/Root.vhd ones
• Engine-Patch Status - Shows at a glance whether the engine is already patched ("Engine: Patched ✓"), so you never have to guess — it's per-install and applies to every instance
• Root Toggle - Enables root the right way for your build: the enable_root_access / bst.feature.rooting flags on classic builds, plus an offline guest-su patch on 5.22.150.1014+. Prompts you to boot a fresh instance once if its su isn't generated yet
• Engine Patch (5.22+) - Patches HD-Player.exe to disable the "doesn't meet security" integrity shutdown, and HD-MultiInstanceManager.exe so root isn't reset back off when you edit instances
• Read/Write Toggle - Switches disk files (fastboot.vdi, Root.vhd) between Normal and Readonly
• Install Magisk Module - Pushes a module .zip into a running instance and flashes it directly over BlueStacks' bundled ADB (magisk --install-module), so you skip BlueStacks' file dialog entirely (it hands Magisk an "Invalid Uri" it can't open). Just close and reopen the instance afterwards to activate it
• Reversible - Every binary patch backs up to a .prepatch.bak; every guest-su patch records the original bytes. "Undo Engine Patch" and toggling root off restore the originals
• Process Handling - Closes all BlueStacks processes (player, services, and the Multi-Instance Manager) before applying changes
• Responsive UI - Long operations run on background threads (QThread) so the window never freezes
• Internationalization - Includes English and Japanese translations

How It Works

BlueStacks changed how it locks down root across versions, so the tool uses two approaches and chooses automatically based on the detected version.

Classic builds (5.22.130 and older, and MSI): root is the original flag-based method. Setting bst.instance.<name>.enable_root_access=1 exposes the guest su. On some builds su only lives at /system/xbin/bstk/su (not on the app PATH), so root-checker apps report "not rooted" even though a shell gets uid=0; the tool adds a /system/xbin/su symlink offline so apps see it too.

Patch-mode builds (5.22.150.1014+): BlueStacks added two locks. First, HD-Player.exe runs a disk-integrity check on boot and force-closes a modified instance with the "illegally tampered" popup. Second, the guest su was rewritten to grant root only to a signed whitelist. The tool defeats both:

1. Engine patch - flips _isDiskVerificationRequired() in HD-Player.exe to return 0, which disables the integrity shutdown and turns on Developer Mode. It also NOPs the routine in HD-MultiInstanceManager.exe that resets enable_root_access to 0.
2. Guest-su patch - opens the instance's Data.vhdx directly (no running instance, no ADB), finds every guest su, and flips its isDeveloperMode() gate to always-grant so root works for every app.

Both patches are located by byte signature, not hard-coded offsets, so they survive minor version rebuilds, and both are fully reversible.

Prerequisites

• Operating System: Windows 10 or later
• BlueStacks Version: BlueStacks 5 or MSI App Player — any current version works, including the latest 5.22.x (see Version Compatibility)
• Administrator Rights: Required for registry access, patching files under Program Files, and terminating BlueStacks processes
• Python (development only): Python 3.7+

Installation

Option 1: Download Executable (Recommended)

1. Download the latest .exe from Releases
2. Right-click the executable and select "Run as administrator"

Note

You do not need to uninstall or downgrade BlueStacks first. Install or keep whatever current version you like — the tool patches it in place. (Downgrade instructions are still kept below for anyone who wants the old approach.)

Option 2: Run from Source

git clone https://github.com/RobThePCGuy/BlueStacks-Root-GUI.git
cd BlueStacks-Root-GUI
python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt
python main.py

Note: Run your terminal as administrator.

Building the Executable

pip install pyinstaller
pyinstaller --onefile --windowed --icon="favicon.ico" --add-data "favicon.ico;." --add-data "tools/e2fsprogs;tools/e2fsprogs" --name BlueStacksRootGUI main.py

Output will be in the dist/ folder.

Note

You normally don't need to build by hand — pushing a version tag (v*) triggers the release.yml workflow, which builds this exact executable on a Windows runner and publishes it to Releases automatically.

Usage Guide

Launch the GUI as administrator. It auto-detects your BlueStacks installation, lists your instances, and shows the engine-patch buttons only when a patch-mode build (5.22.150.1014+) is present. Follow the section that matches your version.

Patch-Mode Builds (5.22.150.1014+)

This is the path for current BlueStacks. You get root for apps without touching /system or installing anything in the guest.

1. Create the instance first - if it's a brand-new install, open BlueStacks once so it builds and boots your instance, then close it. The guest su only appears in Data.vhdx after the first boot.
2. Patch the engine (once per install) - click "Patch BlueStacks Engine (required for root)" → Yes. All BlueStacks processes are closed first, then HD-Player.exe and HD-MultiInstanceManager.exe are patched and backed up.
3. Toggle root (per instance) - tick the instance and click "Toggle Root." This sets the root flags and patches the guest su inside Data.vhdx. If it reports that su isn't there yet, boot the instance once and toggle again.
4. Restart the instance - start it from BlueStacks. It should boot with no security/tamper popup, and root-checker apps (or Kitsune Mask / Magisk) will see root.

Tip

This gets apps working root — enough for most root-requiring apps and root checkers. If you want Magisk/Kitsune-managed root with modules and hiding (Zygisk, Play Integrity Fix, LSPosed, etc.), that's a separate, more involved setup with real emulator gotchas (Zygisk injection, competing-su conflicts, modules that hang boot). It's documented in the companion guide: Root BlueStacks with Kitsune Mask → Magisk Modules & Hiding.

Classic Builds (5.22.130 and older / MSI)

The original flag-based flow, used to install Kitsune Mask into /system.

1. Enable Root & R/W

   • Select your target instance
   • Click "Toggle Root" (turn ON)
   • Click "Toggle R/W" (turn ON)

2. Install Kitsune Mask

   • Download the Kitsune Mask APK — a pinned, hash-verified copy (the original repo is abandoned)
   • Launch the instance via BlueStacks Multi-Instance Manager
   • Install the APK (drag-and-drop)
   • Open the Kitsune Mask app

3. Direct Install to System

   • Tap Install → Next
   • Select "Direct Install to /system"
   • If this option is missing, close and reopen the Kitsune Mask app
   • Let installation complete and reboot when prompted

4. Final Configuration

   • Return to BlueStacks Root GUI
   • Click "Toggle Root" to turn it OFF
   • Leave "Toggle R/W" ON

5. Verify

   • Launch the instance and open Kitsune Mask
   • It should show as installed and active

Keep Root After Updates

Root sticks across normal restarts, but a background BlueStacks auto-update can silently replace the patched files and bring the security check back. If that happens, just re-run "Patch BlueStacks Engine." To stop it from happening, disable the two update paths (Administrator terminal):

sc.exe stop BstHdUpdaterSvc
sc.exe config BstHdUpdaterSvc start= disabled
schtasks /Change /TN "BlueStacksHelper_nxt" /DISABLE

Warning

The scheduled task is the one that matters most. Some builds don't even install the BstHdUpdaterSvc service — the sc.exe lines will report "service does not exist," which is fine — but they still ship the BlueStacksHelper_nxt scheduled task, which can update independently. Disable whichever exist. Setting bst.auto_update="0" in bluestacks.conf does not work; it is silently ignored.

Troubleshooting

Version Compatibility

BlueStacks Version	Root Working?	Method
5.20.x – 5.21.x	Yes	Classic enable_root_access rooting
5.22.x (pre-5.22.150.1014)	Yes	Classic rooting + engine integrity patch to clear the security popup
5.22.150.1014+	Yes	Patch mode: engine patch + Data.vhdx guest-su patch

Verified rooted — every instance reports uid=0 after toggling root:

Edition	Registry key	Version	Mode	Android versions verified
Normal	BlueStacks_nxt	5.22.232.1002	patch	7 (32/64-bit), 9, 11, 13
China	BlueStacks_nxt_cn	5.22.170.6509	patch	7 (32/64-bit), 9, 11, 13
MSI	BlueStacks_msi5	5.22.75.6322	classic	7 (32/64-bit), 9, 11, 13

Note: On classic / MSI builds the guest su is exposed at /system/xbin/bstk/su; on patch-mode builds su is on the PATH directly. bst.feature.rooting resets to 0 on launch, but root stays live via the per-instance enable_root_access flag.

Background: the 5.22 "security" popup

Issue: BlueStacks 5.22+ (October 2025) shows "Android system doesn't meet security requirements" and shuts the instance down when root/R/W is enabled.

Cause: Google replaced SafetyNet with the Play Integrity API in January 2025. BlueStacks 5.22 added a disk-integrity check that detects the modified system and refuses to boot it.

Fix: This tool's engine patch disables that check, so downgrading to 5.21 is no longer required. Downgrade instructions are kept below only for reference.

How to Downgrade to 5.21 (legacy)

You should not need this anymore — it's kept for reference only.

1. Backup your data - Export important app data/saves

2. Complete uninstall

   • Download BSTCleaner
   • Run to remove all BlueStacks files

3. Install BlueStacks 5.21

   • Download from Uptodown Archive
   • Look for version 5.21.x.xxxx (January 2025)

4. Disable auto-updates - see Keep Root After Updates

5. Apply rooting guide - follow the classic-build steps above

Tracking: See Issue #11 for history and discussion.

Common Issues

No instances listed / "Path Not Found"

• Run the GUI as Administrator
• Verify registry keys exist: HKLM\SOFTWARE\BlueStacks_nxt (Normal), HKLM\SOFTWARE\BlueStacks_nxt_cn (China), or HKLM\SOFTWARE\BlueStacks_msi5 (MSI)
• Perform a clean reinstall using the official cleaner tool

"Permission denied" while patching HD-MultiInstanceManager.exe

• This means the Multi-Instance Manager window was open, locking the file. The tool now closes it automatically before patching — make sure you're on the latest version, then re-run "Patch BlueStacks Engine."

"Toggle Root" says su isn't in Data.vhdx yet

• The guest su only materializes after the instance's first boot. Start the instance once, shut it down, and toggle root again.

Root worked, then stopped after a while

• BlueStacks likely auto-updated and reverted the patch. Re-run "Patch BlueStacks Engine," then follow Keep Root After Updates.

R/W toggle doesn't persist

• Ensure BlueStacks processes were fully terminated (kill leftovers in Task Manager if needed)
• Keep R/W ON after installing Kitsune Mask

"Direct Install to /system" option missing

• Verify both Root and R/W are ON before launching the instance
• Close and reopen the Kitsune Mask app within BlueStacks

Installing a module fails with "Invalid Uri"

• BlueStacks' file picker gives Magisk/Kitsune a Windows-style path it can't open. Instead, start the instance, tick it in the GUI, and use "Install Magisk Module (.zip)" — it pushes the module in and flashes it via Magisk for you. Close and reopen the instance to activate it. (If the ADB root shell isn't reachable, it drops the zip in the instance's Download folder so you can flash it by hand.)

Toggle operation errors

• Check the status bar in the GUI for the error message
• A full log is written to %TEMP%\BlueStacksRootGUI.log — helpful when reporting an issue

BlueStacks won't launch after patching (locked-down / corporate PCs)

• Patching HD-Player.exe invalidates its digital signature. Machines that enforce Windows Defender Application Control (WDAC) or strict AppLocker publisher rules may then block the patched binary from running. This does not affect normal home PCs.
• If you're on a managed machine and BlueStacks silently fails to start after patching, use "Undo Engine Patch" to restore the signed original, or run on a machine without those policies.

Development

Project Structure

• main.py - PyQt5 GUI, application logic, threading
• config_handler.py - Reads/writes bluestacks.conf
• instance_handler.py - Modifies .bstk files, handles processes
• registry_handler.py - Reads BlueStacks paths and versions from the Windows Registry
• constants.py - Shared constants (keys, filenames, modes, process list, patch-mode version cutoff)
• admin.py - UAC elevation helpers (relaunch as administrator, network-drive-safe)
• integrity_patch.py / root_persistence.py - Engine patches (5.22+ integrity bypass, keep root enabled) with .prepatch.bak backups
• su_patch.py / su_patch_offline.py - Patch-mode app root: flips the guest su isDeveloperMode gate inside Data.vhdx (bundled VHD/VHDX + ext4 reader, no ADB required)
• ext4_symlink.py - Classic/MSI app root: adds /system/xbin/su in Root.vhd via bundled debugfs (tools/e2fsprogs/)

Dependencies

See requirements.txt. Key dependencies:

• PyQt5
• pywin32
• psutil

Contributing

Contributions are welcome! Please:

• Maintain existing code style and structure
• Use the logging module for debugging output
• Add/update docstrings for new or modified code
• Use background threads for blocking operations to keep the UI responsive
• Update constants.py for new configurable values
• Submit pull requests with clear descriptions
• Open an issue to discuss significant changes before implementing

---

Related Project: Root BlueStacks with Kitsune Mask