BlueStacks Root GUI

---

A one-click tool to root BlueStacks 5. It turns root access on and off from a simple window: no command line, no reverse-engineering, no hunting for an old version. Point it at your BlueStacks, click a couple of buttons, done.

Windows is the primary platform. BlueStacks Air on Apple Silicon Macs is also supported — see Option 3 and Rooting BlueStacks Air. Air needs a different method entirely, because unlike Windows BlueStacks it ships no su for the usual config flag to unlock. The Intel (x86) macOS build is not supported yet.

Tip

The latest BlueStacks now roots, no downgrade required. BlueStacks 5.22 added a security 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. Confirmed working on 5.22.232.1002 / Android 13: the latest official build as of July 2026. If someone told you to downgrade to 5.21, you don't have to anymore.

---

Table of Contents

• Quick Start
• What You'll See
• Installation
• Usage Guide
  • Rooting the Current BlueStacks (Patch Mode)
  • Magisk Modules, Kitsune Mask & Older Builds
  • Keep Root After Updates
  • Rooting BlueStacks Air (macOS)
• Troubleshooting
• How It Works
• Features
• Development
• Contributing
• Credits
• License

---

Quick Start

You don't need to know which BlueStacks version you have; the app detects it and shows you the right buttons. Just run it as administrator and follow along.

1. Install BlueStacks and open it once. Let your instance finish booting, then close it. (The tool can only root an instance that already exists.)
2. Download the tool. Grab the latest .exe from Releases.
3. Right-click the .exe → Run as administrator. It opens on the Dashboard and finds your BlueStacks automatically.
4. Patch the engine. Click the red "Patch BlueStacks Engine (required for root)" button and confirm. Let it finish.

   Don't see that button? You're on an older build that doesn't need it; skip straight to step 5.

5. Turn on root. Click Instances in the left menu, tick the checkbox next to your instance, and click Toggle Root. Watch the progress bar at the bottom and wait for it to finish.
6. Start BlueStacks. It boots with no security popup, and your root apps (Root Checker, Kitsune Mask, Magisk) now see root. Done.

That's the whole thing for most people. Want Magisk with modules and hiding, or you're on an older/MSI build? See the Usage Guide below.

What You'll See

The window has five tabs down the left side. You'll only ever need the first two for basic rooting.

Tab	What it's for
Dashboard	Where BlueStacks was found, the engine-patch button, and how many instances are rooted. Start here.
Instances	Your instances with live Root, R/W and Magisk status, and everything you do to one: Launch, Restart, R/W, and both ways to root.
Modules	Push a Magisk module .zip into a running instance and flash it for you. Optional.
Privacy	Turn BlueStacks' own ads and telemetry off (its config switches, all instances), and optionally block tracker domains inside one instance's guest hosts file. Both reversible. Optional.

A light/dark theme toggle sits in the header, and a progress bar along the bottom shows what the tool is doing during any operation.

Installation

Option 1: Download the Executable (Recommended)

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

You need Windows 10 or later and administrator rights (the tool reads the registry, patches files under Program Files, and closes BlueStacks). You do not need to uninstall or downgrade BlueStacks first: the tool patches whatever current version you have, in place.

Option 2: Run from Source

For developers, or anyone who'd rather run the Python directly. Requires Python 3.7+.

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" --add-data "magisk_assets;magisk_assets" --name BlueStacksRootGUI main.py

Output lands 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.

Option 3: macOS — BlueStacks Air (Apple Silicon)

Important

Apple Silicon only. This supports BlueStacks Air on M-series Macs. The older Intel (x86) macOS build is not supported yet — it is a different product inside: VirtualBox-based, with VHDX disks and an x86 Android guest, none of which the Air method fits. The tool detects the player's architecture and refuses an Intel install rather than touching it, so there is no risk in trying.

Run from source; there is no packaged build yet.

git clone https://github.com/RobThePCGuy/BlueStacks-Root-GUI.git
cd BlueStacks-Root-GUI
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
brew install e2fsprogs        # required: rooting edits the guest ext4
python main.py

Two things are different from Windows, and both are one-time:

1. brew install e2fsprogs. Rooting edits the Android system image with debugfs, which macOS does not ship. The Windows build bundles its own copy; the macOS one uses Homebrew's. The app tells you if it is missing.
2. Grant App Management. Rooting writes back into BlueStacks.app, and since macOS Ventura that needs System Settings → Privacy & Security → App Management for whatever runs the tool (your terminal when running from source). You may need to quit and reopen it afterwards.

You do not need sudo, and normally you will not see a password prompt at all. That is not a shortcut — it is the only thing that works. App Management is granted to an application, not to a user, so a root helper does not inherit your terminal's grant: running the copy as root fails where writing it directly succeeds. Root.qcow2 is already mode rw-rw-rw-, so once App Management is granted the plain write goes through. (The tool still falls back to an authorization prompt for installs whose image genuinely is not user-writable.)

Usage Guide

The Quick Start covers the common case. This section has the full detail, plus the paths for Magisk/Kitsune modules and older builds. Launch the GUI as administrator: it opens on the Dashboard, auto-detects your install, and only shows the engine-patch button when a modern build (5.22.150.1014+) is present.

Rooting the Current BlueStacks (Patch Mode)

This is the path for current BlueStacks (5.22.150.1014 and newer). You get root for apps without touching /system or installing anything inside Android.

1. Create the instance first: if this is a brand-new install, open BlueStacks once so it builds and boots your instance, then close it. Root can't be added until the instance's disk exists.
2. Patch the engine (once per install): on the Dashboard, click "Patch BlueStacks Engine (required for root)" → Yes. All BlueStacks processes are closed first, then the tool patches and backs up the engine files. Until you do this, the Instances page shows a "Patch-mode root is locked" banner with a Fix it shortcut back to the Dashboard.
3. Toggle root (per instance): go to the Instances page, tick the instance, and click "Toggle Root." Watch the progress bar at the bottom: it walks through "Part 1/2: enabling root access..." then "Part 2/2: patching guest su in Data.vhdx..." before the button is usable again. Don't launch the instance while that's running; wait for it to finish. If it says su isn't there yet, a dialog will tell you to 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.

Note

If a background BlueStacks auto-update later replaces the patched files, the Dashboard raises an "auto-update reverted your engine patch" alert with a Re-patch now button. See Keep Root After Updates to stop it happening again.

Tip

This gets apps working root, enough for most root-requiring apps and root checkers. If you want Magisk/Kitsune-managed root with modules (Zygisk via ReZygisk, LSPosed, etc.), that's a separate, more involved setup with real emulator gotchas. It's documented in the companion guide: Root BlueStacks with Kitsune Mask → Magisk Modules & Hiding. Note: Play Integrity does not pass on an emulator; Google limits that to its own Google Play Games, so integrity-gated apps won't work here regardless of modules.

Magisk Modules, Kitsune Mask & Older Builds

Everything past basic root lives in the companion guide: installing Kitsune Mask into /system, choosing and flashing Magisk modules (ReZygisk, LSPosed, module load order), and rooting older or MSI builds. One maintained place beats two half-covered ones.

Tip

➡️ Root BlueStacks with Kitsune Mask: the full written walkthrough. Stuck, or want to share a setup that works? Ask and help out in Discussions there.

One tool-specific note: this app's Modules tab pushes and flashes a module .zip into a running, rooted instance for you. Start the instance, open the Modules tab, pick it, Browse... to the .zip, click Push and flash module, then reopen the instance. It exists because BlueStacks' own file picker hands Magisk an "Invalid Uri" it can't open. (If the ADB root shell isn't reachable, the tool drops the .zip in the instance's Download folder so you can flash it by hand.)

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 click Re-patch now on the Dashboard (or 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, so the sc.exe lines will report "service does not exist," which is fine; 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.

Rooting BlueStacks Air (macOS)

Set up per Option 3 first — brew install e2fsprogs and the App Management permission are both required.

1. Close BlueStacks, then start the tool (python main.py). The Dashboard shows AIR v5.21.x and your data directory.
2. Go to Instances, tick your instance, and click "Root (all instances)".
3. Wait. The pass takes a couple of minutes — most of it is unpacking and repacking a 1.7 GB image.
4. Start BlueStacks. su is now at /system/xbin/su, on the guest PATH, so both adb shell su and root-checker apps see it:

$ hd-adb shell "su -c id"
uid=0(root) gid=0(root) groups=0(root),...

To undo, click the same button (now "Remove Root (all instances)"). It restores the pristine image from the backup the first root made.

Note

On Air the button says "all instances" because it means it: every Air instance boots one shared system image, so there is no per-instance root. This also means a BlueStacks update wipes root — it replaces that image. The tool notices and stops reporting the instance as rooted; just click the button again.

Tip

The Modules tab, the R/W toggle and the Magisk buttons are hidden on Air. They are not missing features to work around: Air has no .bstk files to flip, and the Magisk installer drives Windows VHDs through bundled .exe tools.

Important

While rooted, BlueStacks.app's code signature no longer validates. Root.qcow2 is a sealed resource of the bundle, so changing it invalidates the seal — codesign --verify and spctl both start failing. This is unavoidable for any change to the guest system, not something the tool works around. In practice BlueStacks still launches and runs normally, because macOS does not re-run Gatekeeper on an app that is already installed and has been opened.

Undoing restores the backup byte for byte, which repairs the seal exactly. That is why the backup is kept until the last change is undone, and why undo restores it rather than editing the modification back out.

Everything the tool put on disk lives in two places, both outside the bundle and both removed when you undo: Root.qcow2.prepatch.bak (the pristine image) and Root.qcow2.modstate.json (what is currently applied), in /Users/Shared/Library/Application Support/BlueStacks/.

Troubleshooting

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)
• As a last resort, start fresh: run BlueStacks' official BSTCleaner to remove everything, then reinstall

"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. Click Re-patch now on the Dashboard, 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)

Installing a module fails with "Invalid Uri"

• Don't use BlueStacks' own file picker; use the app's Modules tab instead (see Magisk Modules, Kitsune Mask & Older Builds). Deeper Kitsune/module help lives in the companion guide's Discussions.

Toggle operation errors

• Check the progress bar/status text at the bottom of the window 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.

Version Compatibility

BlueStacks Version	Root Working?	Method
5.20.x to 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

macOS:

BlueStacks	Root Working?	Method
Air (Apple Silicon, arm64)	Yes	Inject su into the shared Root.qcow2 — Air ships none
Intel / x86 macOS build	Not yet	Different product: VirtualBox + VHDX + x86 guest. Detected and skipped, never modified.

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.

How It Works

(For the curious. None of this is needed to use the tool.)

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 rather than hard-coded offsets, so they survive minor version rebuilds, and both are fully reversible.

Note

The patch-mode method, the HD-Player.exe / HD-MultiInstanceManager.exe engine patch and the offline Data.vhdx guest-su patch that root the latest BlueStacks, was contributed by @AndnixSH in PR #27. See Credits.

BlueStacks Air (macOS, Apple Silicon): a third method, because neither of the above applies. Air is a different product — a QEMU/libqvirt VM running an arm64 Android 13 guest, with its config at /Users/Shared/Library/Application Support/BlueStacks/. (The Intel/x86 macOS build is a fourth product — VirtualBox with VHDX disks — and is not supported; detection checks the player's Mach-O architecture and skips it.)

The important difference is that Air ships no su at all. Windows BlueStacks includes a guest su that enable_root_access merely unlocks, which is why flipping that flag roots it. Air's image has no su, no SuperSU and no Magisk anywhere in /system or its ramdisk — its init even tries to import /init.superuser.rc and logs that the file does not exist. The enable_root_access key still exists in Air's bluestacks.conf, and the player still resets bst.feature.rooting to 0 on every launch, but nothing reads them. Setting those flags on Air does nothing.

So the tool adds an su:

1. Converts BlueStacks.app/Contents/img/Root.qcow2 to raw with BlueStacks' own bundled qemu-img, after backing it up outside the bundle.
2. Writes a 223-byte statically-linked aarch64 su into the guest ext4 with debugfs, owned by root with mode 06755. SELinux is disabled on Air, so a classic setuid binary is sufficient — no policy patching. The binary is generated, not downloaded or vendored (see macos_su.py, which includes its full assembly listing).
3. Runs e2fsck, repacks to qcow2, and writes it back with one authorization prompt.

Two consequences worth knowing:

• Root is install-wide, not per-instance. Every Air instance boots that one shared image; there is no per-instance system image, so rooting covers all of them at once.
• A BlueStacks update removes root, because it replaces that image. The tool fingerprints the image and reports "not rooted" once it changes, rather than claiming root you no longer have.

Undo restores the pristine backup, so nothing about the change is one-way.

Features

• Nav-Rail Layout: A left navigation rail splits the app into four pages: Dashboard (install paths, engine-patch state, rooted-instance count), Instances (every per-instance action: Launch/Restart, R/W, and both root methods), Modules (push and flash a Magisk module), and Privacy (turn BlueStacks' own ads/telemetry off, plus an in-guest tracker block). A light/dark theme toggle sits in the header
• Ad and Telemetry Removal: Turns off BlueStacks' own advertising, promo, and stats-upload switches in bluestacks.conf. This is the part that actually stops the ads: they are served by HD-Player.exe on Windows, so nothing changed inside Android can reach them. Measured on 5.22.250.1015, the player's ad and tracker endpoints went from 40 to 0. The switches are found by pattern rather than a fixed list, so an update that renames or adds one is still covered; every original value is recorded for an exact restore, and an optional read-only pin stops BlueStacks turning the stats beacons back on. Reversible in one click
• 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 by its display name with live Root and R/W status (root shows a green highlight when on), including newer instances that use a single Data.vhdx layout (created or cloned), alongside the classic fastboot.vdi/Root.vhd ones
• Engine-Patch Status: The Dashboard's engine button reads its own state at a glance: "Patch BlueStacks Engine (required for root)," "Engine patched (click to Undo)," or "Engine partially patched (click to finish)." It's per-install and applies to every instance
• Patch-Gating Banner: On patch-mode builds, the Instances page shows a banner while the engine is unpatched ("Patch-mode root is locked…") with a Fix it button that jumps straight to the Dashboard, so you can't try to root an instance before the engine is ready
• Update-Revert Alert: If a background auto-update silently replaces the patched files, the Dashboard raises an alert with a one-click Re-patch now button
• 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
• Push and Flash Module: The Modules page 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, and a docked progress bar reports real step-by-step percentages

Development

Project Structure

• main.py: Application entry point and controller; wires the UI to the handlers and owns the background-thread orchestration
• views/: PyQt5 UI package (nav-rail layout)
  • main_window.py: Main window; nav rail, page stack, worker threads, docked progress bar
  • nav_rail.py: Left navigation rail (Dashboard / Instances / Modules / Privacy)
  • dashboard_page.py: Install paths, engine-patch button, update-revert alert, rooted-count stat
  • instances_page.py: Instance grid with Root/R-W/Magisk state, Launch/Restart, and both root methods in one Root group
  • modules_page.py: Pick a running instance, pick a module .zip, push and flash
  • privacy_page.py: Turn BlueStacks' own ads/telemetry off (global config switches), plus the per-instance in-guest tracker block
  • progress.py: Docked status/progress indicator with step percentages
  • theme.py: Light/dark QSS themes and persistence
  • engine_rules.py: Qt-free decision logic for patch-gating and update-revert detection (unit-testable without a QApplication)
• config_handler.py: Reads/writes bluestacks.conf
• instance_handler.py: Modifies .bstk files, handles processes
• registry_handler.py: The single detection entry point. Reads BlueStacks paths and versions from the Windows Registry, and delegates to macos_locator.py on macOS
• constants.py: Shared constants (keys, filenames, modes, process list, patch-mode version cutoff, APP_VERSION)
• admin.py: UAC elevation helpers (relaunch as administrator, network-drive-safe); a no-op on macOS, which elevates per-operation instead
• platform_support.py: Platform flags, and the osascript administrator prompt macOS uses for the one privileged step
• macos_locator.py: Finds a BlueStacks Air install (app bundle, shared data dir, instances) and reports it in registry_handler's shape. Reads the player's Mach-O architecture and fails closed on anything that isn't Apple Silicon, so an Intel install is never mistaken for Air
• macos_root.py: Roots BlueStacks Air by injecting su into the shared Root.qcow2 via bundled qemu-img + Homebrew debugfs, with a backup outside the bundle and an image fingerprint so a BlueStacks update can't leave a stale "rooted" claim
• macos_su.py: Builds the 223-byte statically-linked aarch64 su that gets injected; full assembly listing in the module docstring
• adb_handler.py: Pushes/flashes a module .zip, and installs/removes the Magisk manager app, over BlueStacks' bundled ADB
• 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/)
• magisk_system.py: Offline Magisk-to-system install; stages the DATABIN into Data.vhdx and the /system footprint into Root.vhd, all via bundled debugfs
• magisk_payload.py: Downloads and hash-verifies the latest Kyubi (Magisk) release APK, and extracts the native tools/assets magisk_system.py needs
• rezygisk_payload.py: Downloads and hash-verifies the pinned ReZygisk module (standalone Zygisk for the emulator)
• lsposed_payload.py: Downloads and hash-verifies the pinned LSPosed (Zygisk) module
• ad_settings.py: Turns BlueStacks' own ad/promo/stats switches off in the global bluestacks.conf. Discovers them by pattern so a version update can't silently outdate the list, records originals for an exact restore, and can pin the file read-only
• telemetry_block.py: Null-routes tracker domains in an instance's guest hosts file, offline via Root.vhd. Reaches apps inside the emulator only: BlueStacks' own ads are host-side, so ad_settings.py handles those
• magisk_assets/: Version-pinned system-install assets (config, bootanim.rc, bootanim.rc.gz) bundled for the Magisk system-mode install

Dependencies

See requirements.txt. Key dependencies:

• PyQt5
• pywin32 (Windows only — marked with an environment marker so pip install works on macOS)
• psutil

On macOS, rooting also needs e2fsprogs (brew install e2fsprogs) for debugfs/e2fsck; the Windows build bundles its own copy in tools/e2fsprogs/. qemu-img and adb come from the BlueStacks Air bundle itself, so there is nothing to install for those.

Running Tests

The suite uses pytest with pytest-qt (for the Qt view tests):

pip install -r requirements-dev.txt
pytest

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

Credits

• Rooting the latest BlueStacks (patch mode): the engine patch (HD-Player.exe + HD-MultiInstanceManager.exe) and the offline Data.vhdx guest-su patch that defeat the 5.22.150.1014+ integrity check were contributed by @AndnixSH in PR #27. This tool automates that method; without it there'd be no root on current builds without downgrading.
• Maintainer: @RobThePCGuy: original GUI, the classic flag-based rooting, and the hardening around the patch-mode method (auto-kill Multi-Instance Manager, restore brick-guard, binary-provenance audit).

License

Copyright (C) 2026 Rob Adams Jr (RobThePCGuy)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License v3.0 as published by the Free Software Foundation. It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY: without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See LICENSE for the full text.

In short: you're free to use, study, share, and modify it, but anything you redistribute has to stay open under GPLv3 and keep this attribution. Bundled third-party tools (e.g. tools/e2fsprogs/) keep their own upstream licenses; see that directory for details.

---

Related Project: Root BlueStacks with Kitsune Mask: the full Kitsune Mask, Magisk modules, and hiding guide, plus Discussions for help and sharing setups.