Introducing a new way to review your PRs.

Read the announcement

mustardchef / wsabuilds

Run Windows Subsystem For Android on your Windows 10 and Windows 11 PC using prebuilt binaries with Google Play Store (MindTheGapps) and/or Magisk or KernelSU (root solutions) built in.

View on GitHub

12 documents · Updated Nov 16, 2026

docs / user-facing-documentation

User-Facing Documentation

Overview

This area is the user-facing documentation layer for WSABuilds and the bundled MagiskOnWSA documentation snapshot. The public entry point is README.md: it opens with current high-priority notices about LTS releases and GApps-related breakage, then presents release download buttons for Windows 10/11 and x64/arm64, system requirements, WSA end-of-support context, release schedule notes, and links into the main guide set under Documentation/WSABuilds/. Reviewers should treat README.md as the landing page and navigation hub; changes to installation, update, backup, FAQ, or issue guidance usually need corresponding link/summary updates there.

Licensing context is split between LICENSE, which is the GNU AGPLv3 text for software, and LICENSE-CC-BY-NC-ND, which is Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 text for licensed material. User-visible attribution and third-party project context live in Documentation/…/Credits.md, which explains that the repository distributes unofficial WSA builds produced with MagiskOnWSALocal, WSA-Script-derived workflows, and WSAPatch for Windows 10 support, and states the non-affiliation disclaimers for Microsoft, Google, Android, Windows, and WSA.

Documentation/WSABuilds/ is the primary WSABuilds guide family:

  • Documentation/…/Information.md describes project status, known issues, skipped updates, and a large compatibility matrix of WSA versions against Windows 10/11. It is the place to update broad release-status facts rather than procedural steps.
  • Documentation/…/Installation.md owns the install path from GitHub Releases asset selection through .7z extraction, folder renaming, Run.bat, and the manual Install.ps1 fallback. It also explains why the extracted install folder must be kept because the appx package is registered from unpackaged files.
  • Documentation/…/Updating.md owns the in-place update workflow: turn off WSA and WSA helper tools, extract the new archive contents into the existing install folder, replace files, run Run.bat, then verify the WSA version in settings.
  • Documentation/…/Uninstallation.md owns removal of WSABuilds and Microsoft Store WSA installs, including preserving %LOCALAPPDATA%\Packages\MicrosoftCorporationII.WindowsSubsystemForAndroid_8wekyb3d8bbwe\LocalCache\userdata.vhdx before deleting the app package and extracted WSA folder.
  • Documentation/WSABuilds/Backup and Restore.md expands the userdata workflow: copy userdata.vhdx, remove launch lines from the extracted build's Install.ps1 before reinstalling, restore the VHDX under the WSA package LocalCache, then close startup popups and relaunch WSA.
  • Documentation/…/FAQ.md answers common support questions such as logcat collection, whether the install folder can be deleted, updating WSA/Magisk, virtualization, read-write system partition limits, ADB connection troubleshooting, empty Magisk module lists, and custom Magisk/GApps requests.
  • Documentation/WSABuilds/Having Issues.md is a visual index into common fixes in Documentation/Fix Guides/**; it should stay aligned with any added, renamed, or removed fix guide.
  • Documentation/WSABuilds/Usage Guide.md is a visual index into usage guides for GPU selection, sideloading, moving WSA to another drive, KernelSU, BusyBox, localhost loopback, and removing stale app entries.
  • Documentation/WSABuilds/App Compatibility.md is a large compatibility table for WSA features, apps, and games; it also documents feature-level workarounds such as VPN AppOps and the wsa://[App Package Name] launch URI.
  • Documentation/…/OldBuilds.md is the historical release link catalog for older Windows 10/11 WSA builds.
  • Documentation/WSABuilds/Custom Builds.md describes what users must provide in an issue when requesting a prebuilt custom build: device model, root solution, Magisk variant, GApps choice, and whether to keep Amazon Appstore.

Documentation/Usage Guides/ contains task and post-installation guides that sit below the WSABuilds guide index. Documentation/Usage Guides/Sideloading Guides/Sideloading.md is the sideloading hub and routes users to WSAFiles, WSA-Sideloader, WSAPacman, APK-Installer, or ADB sideloading. Documentation/Usage Guides/General Usage Guides/ owns operational tasks after installation, including changing GPU, moving WSA to another drive or partition, enabling localhost loopback, installing KernelSU/BusyBox, and cleaning up non-existent app entries. Documentation/Usage Guides/Post-Installation Guides/ is organized around build variants: no-root builds, KernelSU builds, Magisk builds, MindTheGapps/no-GApps, Amazon Appstore kept/removed, and Magisk channels such as Stable, Beta, Canary, Alpha, Delta, and Debug. These post-install pages are mostly success/next-step pages with stability status and support links; for example, Magisk variants flag the module-disappears issue, while KernelSU pages direct users to sideload KernelSU Manager.

Documentation/Fix Guides/ owns troubleshooting content. Documentation/Fix Guides/Troubleshooting.md is the escalation guide: check common issues, test official WSA or WSAPackages if needed, file Feedback Hub reports for official WSA failures, then open a GitHub issue or use Discord. Documentation/Fix Guides/Pre-Install Issues/ covers archive extraction, appx/Appx module failures, install script problems, path-too-long, Internet security settings, named resource errors, logon errors, and installer error codes such as 0x80073CF0, 0x80073CF6, 0x80073CF9, 0x80073CFB, 0x80073CFD, and 0x80073D10. Documentation/Fix Guides/Post-Install Issues/ covers runtime failures after registration, including WSA not loading, settings/app crashes, missing icons, keyboard input, Google Play, virtualization, internet access, refused ADB connections, and WSA stopped working.

Documentation/…/PetroSky.md is standalone sponsor copy for PetroSky Pro+ VPS-based Android emulator hosting. It is marketing content, not a troubleshooting or installation guide, so changes there should not be reflected into technical flows unless the README or another doc explicitly links to it.

MagiskOnWSA/docs/ is a separate docs-site snapshot for MagiskOnWSA/MagiskOnWSALocal-style builds. MagiskOnWSA/…/README.md describes build-script prerequisites for Linux/WSL, features, the clone-and-run workflow using ./…/run.sh, generated output/download folders, installing with Run.bat, and FAQs about updating, logcat, Magisk, Play Integrity, virtualization, ADB, custom GApps, and KernelSU. MagiskOnWSA/…/Custom-GApps.md owns the custom GApps offline build procedure using ./build.sh --gapps-brand none, placing renamed OpenGApps or MindTheGapps zips in download, then rebuilding offline. MagiskOnWSA/…/KernelSU.md and MagiskOnWSA/…/KernelSU.md cover KernelSU-specific guidance. MagiskOnWSA/docs/Guides/ mirrors practical WSABuilds usage guides such as ADB sideloading, BusyBox, changing GPU, checksum verification, localhost loopback, moving WSA to an external drive, and third-party sideloading tools. MagiskOnWSA/docs/Fixes/ mirrors many fix guides from Documentation/Fix Guides/** for the docs site. MagiskOnWSA/…/index.html currently redirects immediately to ./Issues.html; if this static site entry point changes, verify whether the target page exists within the covered docs tree or is generated elsewhere.

Coupling

  • If download targets, release names, LTS status, or platform availability change in README.md, also check Documentation/…/Installation.md, Documentation/…/Updating.md, Documentation/…/OldBuilds.md, and Documentation/…/Information.md; users enter through README download buttons but procedural docs often repeat the same release assumptions.
  • If the install scripts, archive shape, or required extracted folder name change, update both Documentation/…/Installation.md and the troubleshooting guides that diagnose install failures, especially Documentation/Fix Guides/Pre-Install Issues/Fix Error 0x80073CF0.md, Documentation/Fix Guides/Pre-Install Issues/FixInstallps1.md, and Documentation/Fix Guides/Pre-Install Issues/FixPathTooLong.md, because those fixes rely on archive extraction, folder renaming, Run.bat, and Install.ps1 behavior.
  • If the WSA package identity or userdata path changes, update Documentation/…/Installation.md, Documentation/…/Uninstallation.md, Documentation/WSABuilds/Backup and Restore.md, Documentation/…/FAQ.md, and MagiskOnWSA/…/README.md; all of them cite %LOCALAPPDATA%\Packages\MicrosoftCorporationII.WindowsSubsystemForAndroid_8wekyb3d8bbwe or its LocalCache\userdata.vhdx/diagnostics locations.
  • If a fix guide is added, deleted, or renamed under Documentation/Fix Guides/**, update the routing pages Documentation/WSABuilds/Having Issues.md and Documentation/Fix Guides/Troubleshooting.md, and check the mirrored page under MagiskOnWSA/docs/Fixes/ when one exists; otherwise users may see broken or inconsistent support paths.
  • If a usage guide is added, deleted, or renamed under Documentation/Usage Guides/**, update Documentation/WSABuilds/Usage Guide.md and any corresponding mirror under MagiskOnWSA/docs/Guides/; sideloading and KernelSU pages cross-link heavily, so broken links can strand post-install users.
  • If root/GApps/Amazon Appstore build variants change, update the variant-specific post-install pages under Documentation/Usage Guides/Post-Installation Guides/**, Documentation/WSABuilds/Custom Builds.md, Documentation/…/FAQ.md, and MagiskOnWSA/…/README.md; these docs independently name Magisk variants, KernelSU/no-root choices, MindTheGapps, custom GApps, and whether Amazon Appstore is retained.
  • If third-party project attributions, license usage, or affiliation language changes, check Documentation/…/Credits.md, LICENSE, LICENSE-CC-BY-NC-ND, and the trademark/disclaimer footer in MagiskOnWSA/…/README.md; legal-facing claims are spread across both repository-root license files and user-visible credit pages.

Risks

  • MagiskOnWSA/…/index.html redirects to ./Issues.html, but MagiskOnWSA/docs/** as read for this doc did not include an Issues.html file. If the static docs site is served directly from this tree without a generated Issues.html, users landing on MagiskOnWSA/…/index.html will be sent to a missing page.
  • Documentation/WSABuilds/Having Issues.md is a manually maintained link index over many files under Documentation/Fix Guides/**. If a fix guide path changes without updating this file, the main support entry point will keep sending users to stale GitHub blob URLs.
  • Documentation/WSABuilds/Backup and Restore.md instructs users to edit the generated Install.ps1 by removing Start-Process lines before restoring userdata.vhdx. If generated install script launch commands change, the restore guide can make users edit the wrong lines and block data restoration.