waydroid_script: adding GApps, Magisk and ARM translation to Waydroid

What waydroid_script adds to an existing Waydroid install

Waydroid gives you a containerised Android on Linux, but a vanilla image ships without Google services, without root, and without a way to run ARM-only apps on an x86_64 host. waydroid_script is the post-install layer for those three gaps. Its install targets are gapps, magisk, libndk, libhoudini, widevine, smartdock and microg, plus two hacks (nodataperm, hidestatusbar) and a certified command that prints the Android device ID you need for Google's uncertified device registration page.

The intended user is someone who already has Waydroid booting and now wants Play Store, Zygisk modules, or a game that only ships an ARM APK. It is not a Waydroid installer, and the README never claims to be one. The project is GPL-3.0 and written in Python, with the interactive menu built on InquirerPy and downloads handled through requests.

How the install targets work: images, downloads and patched files

The repository is a single main.py plus bin/, stuff/ and tools/ directories, with requirements.txt listing tqdm, requests and InquirerPy. Each install target follows the same shape: the script fetches a payload, then writes it into the Waydroid image or system partition. The README is explicit about provenance for two of them. libndk_translation comes from guybrush firmware, and libhoudini is Intel's library pulled from Microsoft's WSA 11 image, reported as version 11.0.1b_y.38765.m for the 32-bit side and 11.0.1b_z.38765.m for houdini64.

Magisk is not applied live. The README states it will be installed on the next boot, and that Zygisk and modules such as LSPosed should work afterwards. Updating Magisk means either using Direct Install into system partition or running the script again. The nodataperm hack works differently from the others: it replaces /system/framework/service.jar and sets persist.sys.nodataperm whenever an app opens, so a script can chmod the Android data directories to 777. The README calls this a temporary hack against an Android 11 permission issue and names sdcardfs or esdfs as the correct fix, both of which require recompiling the kernel or the WayDroid image.

Installing waydroid_script and running a first gapps install

The README gives one setup path: clone, create a virtual environment, install the three Python dependencies, then run main.py with sudo because the script writes into system paths. lzip is a separate system dependency and must be installed through your distribution's package manager first (pacman, apt, dnf or zypper, depending on the distribution).

git clone https://github.com/casualsnek/waydroid_script
cd waydroid_script
python3 -m venv venv
venv/bin/pip install -r requirements.txt
sudo venv/bin/python3 main.py

Running main.py with no arguments opens the interactive terminal interface. For scripted use, the README documents subcommands. Installing OpenGApps is the first real use case:

sudo venv/bin/python3 main.py install gapps
waydroid show-full-ui

After Waydroid finishes booting, the README says to run the google command (the command-line section lists it as certified) to print the numeric Android ID. You enter that ID at google.com/android/uncertified, wait 10 to 20 minutes for registration, then clear Google Play Services' cache and try logging in. If you prefer the same work without the menu, the equivalent install, uninstall and hack commands are:

sudo venv/bin/python3 main.py install {gapps, magisk, libndk, libhoudini, nodataperm, smartdock, microg, mitm}
sudo venv/bin/python3 main.py uninstall {gapps, magisk, libndk, libhoudini, nodataperm, smartdock, microg}
sudo venv/bin/python3 main.py hack {nodataperm, hidestatusbar}

The mitm target takes a certificate, for example sudo venv/bin/python3 main.py install mitm --ca-cert mycert.pem, which installs a self-signed CA into the Android image for traffic interception.

The nodataperm hack is the part that can break your boot

Everything else in the script is additive. nodataperm is not. The README carries a warning that it was tested on lineage-18.1-20230128-VANILLA-waydroid_x86_64.img, that it replaces /system/framework/service.jar, and that this may prevent WayDroid from booting. The stated recovery is sudo venv/bin/python3 main.py uninstall nodataperm. If the image will not boot far enough for that to work, you are re-flashing the Waydroid image.

The README offers a lower-risk alternative: run the chmod commands directly inside sudo waydroid shell. That version has to be repeated every time a new game is installed, but it does not touch service.jar. If your goal is only to stop specific games from freezing on a black screen (the README names Arknights and PUNISHING: GRAY RAVEN), the shell route costs you a few commands per install and removes the boot risk entirely. The script route is the one to choose only if you are comfortable rebuilding the image.

A second limitation is scope. The README states plainly that the script only focuses on Magisk installation and points to nitanmarcel/waydroid-magisk for anything beyond that. There is no rollback story documented for gapps, libndk or libhoudini beyond the uninstall subcommands, and no version pinning for the downloaded payloads.

libndk versus libhoudini: picking an ARM translation layer

Both targets exist to run ARM-only Android apps on an x86_64 Waydroid host, and they are alternatives rather than companions. The README's only guidance is that libndk seems to have better performance than libhoudini on AMD. That is a hedged statement, not a benchmark, and no numbers are published.

The two differ in origin. libndk comes from guybrush firmware; libhoudini is Intel's, taken from Microsoft's WSA 11 image, and the README pins its versions. If you are on Intel hardware, libhoudini is the vendor-matched option. If you are on AMD, the README nudges you toward libndk. Installing both is not described anywhere as supported, so treat this as a pick-one decision and use the uninstall subcommand before switching.

Where waydroid_script sits next to waydroid-magisk and manual patching

The closest alternative named in the README is nitanmarcel/waydroid-magisk, which the project itself recommends for Magisk management beyond installation. The difference in approach is breadth against depth. waydroid_script is a menu of unrelated payloads (Google apps, root, ARM translation, DRM, microG, a certificate installer) applied to an image. waydroid-magisk is a Magisk-focused tool, which is why the README routes update and module-management questions there instead of extending its own Magisk code.

The other alternative is doing it by hand: pulling OpenGApps or a translation library yourself and copying files into the Waydroid image. That gives you control over versions and provenance, at the cost of re-deriving the paths and boot behaviour that main.py already encodes. For the nodataperm case specifically, the README's own in-shell chmod sequence is the manual alternative, and it is the safer one.

Maintenance, licensing and what to check before you run it

The repository is not archived, and the last push was on 2026-09-11, which is recent enough that the code is being touched. There are no retrieved releases, so installation is from the main branch: you get whatever main.py currently is, and there is no tagged version to pin against. That matters for reproducibility, because the script downloads external payloads whose versions are not all documented (libhoudini's are, libndk's are not).

The licence is GPL-3.0. That is a copyleft licence, and it governs the script itself. It does not grant you rights to the payloads the script downloads: OpenGApps, Magisk Delta, microG, Smart Dock and the Intel and guybrush libraries each carry their own terms, and redistributing a patched Waydroid image is a different question from running the script. If you plan to ship an image to other people, check each component's licence separately. Nothing here is legal advice.

The repository also carries Nix packaging (flake.nix, flake.lock, default.nix, package.nix), which the README does not document. If you use Nix, that is the entry point to inspect; if you do not, the venv path above is the documented one.

Editorial conclusion

Adopt waydroid_script if you already run Waydroid on x86_64 and need Google Play services, Magisk, or ARM translation for apps that have no x86 build, and you accept that it edits the Waydroid image directly. Do not use it as a Waydroid installer, on aarch64 hosts, or on an image you cannot rebuild, because the nodataperm hack replaces /system/framework/service.jar and the README warns this may stop WayDroid from booting. Before running anything, confirm your host architecture, install lzip, and check which Waydroid image you are on so you can re-flash it if a patch goes wrong.

Frequently asked questions

Official sources

1. casualsnek/waydroid_script on GitHub
2. Issues
3. License: GPL-3.0
4. README