{"id":35225634,"url":"https://github.com/robthepcguy/bluestacks-root-gui","last_synced_at":"2026-07-26T21:00:23.807Z","repository":{"id":270931731,"uuid":"911887034","full_name":"RobThePCGuy/BlueStacks-Root-GUI","owner":"RobThePCGuy","description":"A python application to toggle root access and enable read/write (R/W) permissions for your BlueStacks instances.","archived":false,"fork":false,"pushed_at":"2026-07-19T03:57:34.000Z","size":2956,"stargazers_count":94,"open_issues_count":0,"forks_count":12,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-07-19T05:15:29.482Z","etag":null,"topics":["android-emulator","android-rooting","bluestacks","bluestacks-2025","bluestacks-5","bluestacks-tools","root-gui","root-tool"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RobThePCGuy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-04T05:22:33.000Z","updated_at":"2026-07-19T03:57:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"9a10d416-428c-48cf-8612-5c4eee34840f","html_url":"https://github.com/RobThePCGuy/BlueStacks-Root-GUI","commit_stats":null,"previous_names":["robthepcguy/bluestacks-root-gui"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/RobThePCGuy/BlueStacks-Root-GUI","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobThePCGuy%2FBlueStacks-Root-GUI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobThePCGuy%2FBlueStacks-Root-GUI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobThePCGuy%2FBlueStacks-Root-GUI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobThePCGuy%2FBlueStacks-Root-GUI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RobThePCGuy","download_url":"https://codeload.github.com/RobThePCGuy/BlueStacks-Root-GUI/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobThePCGuy%2FBlueStacks-Root-GUI/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35928365,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-26T02:00:06.503Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android-emulator","android-rooting","bluestacks","bluestacks-2025","bluestacks-5","bluestacks-tools","root-gui","root-tool"],"created_at":"2025-12-30T01:04:45.953Z","updated_at":"2026-07-26T21:00:23.793Z","avatar_url":"https://github.com/RobThePCGuy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BlueStacks Root GUI\n\n[![GitHub Repo Stars](https://img.shields.io/github/stars/RobThePCGuy/BlueStacks-Root-GUI?style=social)](https://github.com/RobThePCGuy/BlueStacks-Root-GUI)\n[![YouTube Video Views](https://img.shields.io/youtube/views/zpihBs3FtEc?style=social)](https://youtu.be/zpihBs3FtEc)\n[![Last Updated](https://img.shields.io/github/last-commit/RobThePCGuy/BlueStacks-Root-GUI)](https://github.com/RobThePCGuy/BlueStacks-Root-GUI/commits/master)\n\n---\n\n\u003cimg width=\"714\" height=\"527\" alt=\"BlueStacks Root GUI Dashboard\" src=\"docs/dashboard.png\" /\u003e\n\n**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.\n\n\u003e [!TIP]\n\u003e **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.\n\n---\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [What You'll See](#what-youll-see)\n- [Installation](#installation)\n- [Usage Guide](#usage-guide)\n  - [Rooting the Current BlueStacks (Patch Mode)](#rooting-the-current-bluestacks-patch-mode)\n  - [Magisk Modules, Kitsune Mask \u0026 Older Builds](#magisk-modules-kitsune-mask--older-builds)\n  - [Keep Root After Updates](#keep-root-after-updates)\n- [Troubleshooting](#troubleshooting)\n- [How It Works](#how-it-works)\n- [Features](#features)\n- [Development](#development)\n- [Contributing](#contributing)\n- [Credits](#credits)\n- [License](#license)\n\n---\n\n## Quick Start\n\nYou 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.\n\n1. **Install BlueStacks and open it once.** Let your instance finish booting, then close it. (The tool can only root an instance that already exists.)\n2. **Download the tool.** Grab the latest `.exe` from **[Releases](https://github.com/RobThePCGuy/BlueStacks-Root-GUI/releases)**.\n3. **Right-click the `.exe` → Run as administrator.** It opens on the **Dashboard** and finds your BlueStacks automatically.\n4. **Patch the engine.** Click the red **\"Patch BlueStacks Engine (required for root)\"** button and confirm. Let it finish.\n   \u003e Don't see that button? You're on an older build that doesn't need it; skip straight to step 5.\n5. **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.\n6. **Start BlueStacks.** It boots with no security popup, and your root apps (Root Checker, Kitsune Mask, Magisk) now see root. **Done.**\n\nThat'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](#usage-guide) below.\n\n## What You'll See\n\nThe window has five tabs down the left side. You'll only ever need the first two for basic rooting.\n\n| Tab | What it's for |\n|-----|---------------|\n| **Dashboard** | Where BlueStacks was found, the engine-patch button, and how many instances are rooted. **Start here.** |\n| **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. |\n| **Modules** | Push a Magisk module `.zip` into a running instance and flash it for you. Optional. |\n| **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. |\n\nA **light/dark theme** toggle sits in the header, and a **progress bar** along the bottom shows what the tool is doing during any operation.\n\n## Installation\n\n### Option 1: Download the Executable (Recommended)\n\n1. Download the latest `.exe` from **[Releases](https://github.com/RobThePCGuy/BlueStacks-Root-GUI/releases)**.\n2. Right-click it and choose **\"Run as administrator.\"**\n\nYou 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.\n\n### Option 2: Run from Source\n\nFor developers, or anyone who'd rather run the Python directly. Requires **Python 3.7+**.\n\n```bash\ngit clone https://github.com/RobThePCGuy/BlueStacks-Root-GUI.git\ncd BlueStacks-Root-GUI\npython -m venv venv\n.\\venv\\Scripts\\activate\npip install -r requirements.txt\npython main.py\n```\n\n**Note:** Run your terminal as administrator.\n\n### Building the Executable\n\n```bash\npip install pyinstaller\npyinstaller --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\n```\n\nOutput lands in the `dist/` folder.\n\n\u003e [!NOTE]\n\u003e 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](https://github.com/RobThePCGuy/BlueStacks-Root-GUI/releases)** automatically.\n\n## Usage Guide\n\nThe [Quick Start](#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.\n\n### Rooting the Current BlueStacks (Patch Mode)\n\nThis 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.\n\n1. **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.\n2. **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.\n3. **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.\n4. **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.\n\n\u003e [!NOTE]\n\u003e 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](#keep-root-after-updates) to stop it happening again.\n\n\u003e [!TIP]\n\u003e 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 \u0026 Hiding](https://github.com/RobThePCGuy/Root-Bluestacks-with-Kitsune-Mask#magisk-modules--hiding-advanced)**. 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.\n\n### Magisk Modules, Kitsune Mask \u0026 Older Builds\n\nEverything 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.\n\n\u003e [!TIP]\n\u003e **➡️ [Root BlueStacks with Kitsune Mask](https://github.com/RobThePCGuy/Root-Bluestacks-with-Kitsune-Mask)**: the full written walkthrough.\n\u003e Stuck, or want to share a setup that works? Ask and help out in **[Discussions](https://github.com/RobThePCGuy/Root-Bluestacks-with-Kitsune-Mask/discussions)** there.\n\nOne 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.)\n\n### Keep Root After Updates\n\nRoot 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):\n\n```powershell\nsc.exe stop BstHdUpdaterSvc\nsc.exe config BstHdUpdaterSvc start= disabled\nschtasks /Change /TN \"BlueStacksHelper_nxt\" /DISABLE\n```\n\n\u003e [!WARNING]\n\u003e 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.\n\n## Troubleshooting\n\n### Common Issues\n\n**No instances listed / \"Path Not Found\"**\n- Run the GUI as **Administrator**\n- Verify registry keys exist: `HKLM\\SOFTWARE\\BlueStacks_nxt` (Normal), `HKLM\\SOFTWARE\\BlueStacks_nxt_cn` (China), or `HKLM\\SOFTWARE\\BlueStacks_msi5` (MSI)\n- As a last resort, start fresh: run BlueStacks' official **[BSTCleaner](https://support.bluestacks.com/hc/en-us/articles/360057724751)** to remove everything, then reinstall\n\n**\"Permission denied\" while patching `HD-MultiInstanceManager.exe`**\n- 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.\"\n\n**\"Toggle Root\" says `su` isn't in `Data.vhdx` yet**\n- The guest `su` only materializes after the instance's first boot. Start the instance once, shut it down, and toggle root again.\n\n**Root worked, then stopped after a while**\n- BlueStacks likely auto-updated and reverted the patch. Click **Re-patch now** on the Dashboard, then follow [Keep Root After Updates](#keep-root-after-updates).\n\n**R/W toggle doesn't persist**\n- Ensure BlueStacks processes were fully terminated (kill leftovers in Task Manager if needed)\n\n**Installing a module fails with \"Invalid Uri\"**\n- Don't use BlueStacks' own file picker; use the app's **Modules** tab instead (see [Magisk Modules, Kitsune Mask \u0026 Older Builds](#magisk-modules-kitsune-mask--older-builds)). Deeper Kitsune/module help lives in the [companion guide's Discussions](https://github.com/RobThePCGuy/Root-Bluestacks-with-Kitsune-Mask/discussions).\n\n**Toggle operation errors**\n- Check the progress bar/status text at the bottom of the window for the error message\n- A full log is written to `%TEMP%\\BlueStacksRootGUI.log`, helpful when reporting an issue\n\n**BlueStacks won't launch after patching (locked-down / corporate PCs)**\n- 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.\n- 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.\n\n### Version Compatibility\n\n| BlueStacks Version | Root Working? | Method |\n|-------------------|---------------|--------|\n| 5.20.x to 5.21.x | Yes | Classic `enable_root_access` rooting |\n| 5.22.x (pre-5.22.150.1014) | Yes | Classic rooting + engine integrity patch to clear the security popup |\n| 5.22.150.1014+ | Yes | Patch mode: engine patch + `Data.vhdx` guest-`su` patch |\n\n**Verified rooted**: every instance reports `uid=0` after toggling root:\n\n| Edition | Registry key | Version | Mode | Android versions verified |\n|---------|--------------|---------|------|---------------------------|\n| Normal | `BlueStacks_nxt` | 5.22.232.1002 | patch | 7 (32/64-bit), 9, 11, 13 |\n| China | `BlueStacks_nxt_cn` | 5.22.170.6509 | patch | 7 (32/64-bit), 9, 11, 13 |\n| MSI | `BlueStacks_msi5` | 5.22.75.6322 | classic | 7 (32/64-bit), 9, 11, 13 |\n\n\u003e **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.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eBackground: the 5.22 \"security\" popup\u003c/b\u003e\u003c/summary\u003e\n\n**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.\n\n**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.\n\n**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.\n\n\u003c/details\u003e\n\n\u003ca id=\"how-to-downgrade-to-521-legacy\"\u003e\u003c/a\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eHow to Downgrade to 5.21 (legacy)\u003c/b\u003e\u003c/summary\u003e\n\nYou should not need this anymore; it's kept for reference only.\n\n1. **Backup your data** - Export important app data/saves\n\n2. **Complete uninstall**\n   - Download **[BSTCleaner](https://support.bluestacks.com/hc/en-us/articles/360057724751)**\n   - Run to remove all BlueStacks files\n\n3. **Install BlueStacks 5.21**\n   - Download from **[Uptodown Archive](https://bluestacks-app-player.en.uptodown.com/windows/versions)**\n   - Look for version **5.21.x.xxxx** (January 2025)\n\n4. **Disable auto-updates** - see [Keep Root After Updates](#keep-root-after-updates)\n\n5. **Apply rooting guide** - follow the classic-build steps above\n\n\u003c/details\u003e\n\n**Tracking:** See [Issue #11](https://github.com/RobThePCGuy/Root-Bluestacks-with-Kitsune-Mask/issues/11) for history and discussion.\n\n## How It Works\n\n*(For the curious. None of this is needed to use the tool.)*\n\nBlueStacks changed how it locks down root across versions, so the tool uses two approaches and chooses automatically based on the detected version.\n\n**Classic builds (5.22.130 and older, and MSI):** root is the original flag-based method. Setting `bst.instance.\u003cname\u003e.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.\n\n**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:\n\n1. **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.\n2. **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**.\n\nBoth patches are located by byte signature rather than hard-coded offsets, so they survive minor version rebuilds, and both are fully reversible.\n\n\u003e [!NOTE]\n\u003e 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](https://github.com/AndnixSH)** in [PR #27](https://github.com/RobThePCGuy/BlueStacks-Root-GUI/pull/27). See [Credits](#credits).\n\n## Features\n\n- **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\n- **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\n- **Auto-Detection**: Discovers BlueStacks installation paths via the Windows Registry (Normal, China, and MSI editions) and picks the right rooting method per version automatically\n- **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\n- **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\n- **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\n- **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\n- **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\n- **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\n- **Read/Write Toggle**: Switches disk files (`fastboot.vdi`, `Root.vhd`) between `Normal` and `Readonly`\n- **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\n- **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\n- **Process Handling**: Closes all BlueStacks processes (player, services, and the Multi-Instance Manager) before applying changes\n- **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\n\n## Development\n\n### Project Structure\n\n- `main.py`: Application entry point and controller; wires the UI to the handlers and owns the background-thread orchestration\n- `views/`: PyQt5 UI package (nav-rail layout)\n  - `main_window.py`: Main window; nav rail, page stack, worker threads, docked progress bar\n  - `nav_rail.py`: Left navigation rail (Dashboard / Instances / Modules / Privacy)\n  - `dashboard_page.py`: Install paths, engine-patch button, update-revert alert, rooted-count stat\n  - `instances_page.py`: Instance grid with Root/R-W/Magisk state, Launch/Restart, and both root methods in one Root group\n  - `modules_page.py`: Pick a running instance, pick a module `.zip`, push and flash\n  - `privacy_page.py`: Turn BlueStacks' own ads/telemetry off (global config switches), plus the per-instance in-guest tracker block\n  - `progress.py`: Docked status/progress indicator with step percentages\n  - `theme.py`: Light/dark QSS themes and persistence\n  - `engine_rules.py`: Qt-free decision logic for patch-gating and update-revert detection (unit-testable without a `QApplication`)\n- `config_handler.py`: Reads/writes `bluestacks.conf`\n- `instance_handler.py`: Modifies `.bstk` files, handles processes\n- `registry_handler.py`: Reads BlueStacks paths and versions from the Windows Registry\n- `constants.py`: Shared constants (keys, filenames, modes, process list, patch-mode version cutoff, `APP_VERSION`)\n- `admin.py`: UAC elevation helpers (relaunch as administrator, network-drive-safe)\n- `adb_handler.py`: Pushes/flashes a module `.zip`, and installs/removes the Magisk manager app, over BlueStacks' bundled ADB\n- `integrity_patch.py` / `root_persistence.py`: Engine patches (5.22+ integrity bypass, keep root enabled) with `.prepatch.bak` backups\n- `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)\n- `ext4_symlink.py`: Classic/MSI app root; adds `/system/xbin/su` in `Root.vhd` via bundled `debugfs` (`tools/e2fsprogs/`)\n- `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`\n- `magisk_payload.py`: Downloads and hash-verifies the latest Kyubi (Magisk) release APK, and extracts the native tools/assets `magisk_system.py` needs\n- `rezygisk_payload.py`: Downloads and hash-verifies the pinned ReZygisk module (standalone Zygisk for the emulator)\n- `lsposed_payload.py`: Downloads and hash-verifies the pinned LSPosed (Zygisk) module\n- `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\n- `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\n- `magisk_assets/`: Version-pinned system-install assets (`config`, `bootanim.rc`, `bootanim.rc.gz`) bundled for the Magisk system-mode install\n\n### Dependencies\n\nSee `requirements.txt`. Key dependencies:\n- PyQt5\n- pywin32\n- psutil\n\n### Running Tests\n\nThe suite uses `pytest` with `pytest-qt` (for the Qt view tests):\n\n```bash\npip install -r requirements-dev.txt\npytest\n```\n\n## Contributing\n\nContributions are welcome. Please:\n\n- Maintain existing code style and structure\n- Use the `logging` module for debugging output\n- Add/update docstrings for new or modified code\n- Use background threads for blocking operations to keep the UI responsive\n- Update `constants.py` for new configurable values\n- Submit pull requests with clear descriptions\n- Open an issue to discuss significant changes before implementing\n\n## Credits\n\n- **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](https://github.com/AndnixSH)** in [PR #27](https://github.com/RobThePCGuy/BlueStacks-Root-GUI/pull/27). This tool automates that method; without it there'd be no root on current builds without downgrading.\n- **Maintainer:** [@RobThePCGuy](https://github.com/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).\n\n## License\n\nCopyright (C) 2026 Rob Adams Jr ([RobThePCGuy](https://github.com/RobThePCGuy))\n\nThis 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](LICENSE) for the full text.\n\nIn 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.\n\n---\n\n**Related Project:** [Root BlueStacks with Kitsune Mask](https://github.com/RobThePCGuy/Root-Bluestacks-with-Kitsune-Mask/): the full Kitsune Mask, Magisk modules, and hiding guide, plus [Discussions](https://github.com/RobThePCGuy/Root-Bluestacks-with-Kitsune-Mask/discussions) for help and sharing setups.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobthepcguy%2Fbluestacks-root-gui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobthepcguy%2Fbluestacks-root-gui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobthepcguy%2Fbluestacks-root-gui/lists"}