Android On Linux, Except Someone Actually Asks You Stuff
Running Android apps on your Linux desktop is a vibe. You open the app that refuses to exist on desktop and it sits there in a window on your Wayland session. The flex is real. The setup though? Not so much.
Installing Waydroid has always been the chore nobody warns you about. It is the part of the project that turns a good idea into a whole evening of wiki safari. This is the part this installer exists to kill.
One honest caveat before we go anywhere. Waydroid is a container running Android under the hood, so it is not magic. Apps that lean hard on SafetyNet or Play Integrity checks, which is a lot of banking apps and a bunch of streaming ones, can refuse to run even after a clean install. That is an Android container reality, not something an installer can patch away. If your must have app is a banking app, keep that in mind.
Waydroid has always had a "read the whole wiki for your specific distro" problem. Arch people do one thing, Fedora people do another, Debian people do a third, and somewhere in there you are building kernel modules and hoping you picked the right mirror. It is a whole project before you even get to the fun part.
So I made a script. A small, friendly, menu driven bash script that does the boring parts for you and actually asks what you want before it goes and touches your system.
What You Need Before You Run the Waydroid Installer
Keep the checklist short, because it only has three boxes.
- A Wayland session. Waydroid needs Wayland to show the Android window. If you are on a bare X11 desktop, the whole thing does not get off the ground, and no installer script can fix that for you.
- Sudo privileges. It installs packages, writes repos, and talks to systemd, so you need a sudoer account. That is not optional.
- A kernel that provides binder and ashmem. Waydroid talks to the Linux kernel through those two drivers. Most distro kernels ship them, and on Arch this script will help you build them if yours does not.
That is the whole checklist. No account signups, no platform-specific hoops, nothing hidden. If your machine is missing a piece, the script says so instead of pretending otherwise.
The Whole Point: Stop Assuming
Here is the thing that bugged me about every other installer I tried. They assume. They assume you are on Arch. They assume your kernel already has the drivers. They assume you know which mirror is fast. Assumptions are how you end up with a half broken install and a folder of regrets.
This script is the opposite. It greets you, figures out your distro and package manager on its own, and then asks you a handful of real questions up front. Vanilla or GAPPS? Build the kernel modules or skip them? Fastest mirror or your own pick? It does not silently do things you did not ask for. That is the whole pitch.
What It Actually Does
Depending on what you pick, it will:
- Detect your distro and package manager and install Waydroid the right way for it. Arch and Arch based get AUR packages. Fedora and RHEL get the COPR repo. Debian and Ubuntu get the official apt repo. openSUSE gets the Waydroid package from the openSUSE build service. It matches the tool to the machine.
- Offer the binder and ashmem kernel module step on Arch style systems, where those drivers are not always built in, or let you skip it if your kernel already has them. On other distros it just warns you to check, since those kernels usually ship the drivers built in.
- Grab the Android image from the fastest mirror it can find. SourceForge has a habit of handing you a slow one, so it tests a few sources and picks whichever answers fastest. Official OTA, SourceForge gateway, or a community GitHub mirror. You can still type in a custom OTA URL if you are that person.
- Let you choose between Vanilla and GAPPS. No Google, or the full Google apps experience. Your call, not its.
- Respect your proxy. It notices an existing HTTPS_PROXY and even lets you enable one for the download, which is the fix for a lot of slow or flaky pulls.
- Start and enable the container service so it is actually ready to go.
- Uninstall everything cleanly if you change your mind. No guesswork, no leftover mess.
And if it cannot figure out your setup? It says so instead of guessing wrong. That alone is worth it.
The Boring Part That Saves You
The binder and ashmem kernel module step is the one that trips people up, mostly on Arch. If your kernel does not have those drivers, Waydroid just will not run. On Arch the script offers to build them for you against whichever headers you pick, from linux-headers up to the xanmod anbox headers, or you can skip straight past it if your modules are already there. It is the slow part, but it is the part that makes everything else work. On Fedora, Debian or openSUSE it does not run this step at all, it just reminds you to check that your kernel ships them, because most distro kernels already do.
What Happens After
Pick GAPPS and you give it a few minutes on first boot while Play services settle in. That is normal, not broken. Want to update the Android image later? sudo waydroid upgrade. Want to launch the session from your desktop? waydroid session start. It even grabs waydroid_script for you if you ask, so you can run the extra fixes that make more apps behave. That lives in your autodroid config folder.
Why It Exists
I got tired of paste in these five commands and hope style installs. I wanted one script that asks a few questions, does the right thing for the machine in front of it, and gets out of the way. That is it. No grand ambition, no platform. It sits neatly beside the other Linux and automation tools I keep grinding on, like the Vim game I built to make muscle memory addictive and the automated student pipeline for TestPortal. Same energy, smaller scope.
It is free, GPL-3.0, and on GitHub. Clone it, run ./install.sh, pick your poison. If something breaks, the uninstall flag is cleaner than the original Arch script ever was. That is the least I could do.
Where People Get Stuck
A few pitfalls you can skip with your eyes closed because the script handles them.
- Trying to run it on X11. Waydroid needs Wayland. Check your session before you blame the installer.
- Picking slow mirrors by hand. SourceForge sometimes routes you to a slow host. Just let the speed test choose for you.
- Quitting early on GAPPS. Play services take a few minutes to settle on first boot. That is normal, not a hang.
- Missing binder and ashmem. If the container will not start, this is usually the culprit, and on Arch the script offers to build them.
- Forgetting to start the container service. The script can start and enable it for you, so let it.
None of these are new discoveries, they are just the ones that actually bite. The script was built around them.
TL;DR Because Respect Your Attention
- One bash script, menu driven, works across Arch, Fedora, Debian, Ubuntu and openSUSE.
- Asks what you want instead of assuming and doing it anyway.
- Detects your package manager and builds kernel modules only where needed.
- Downloads the Android image from the fastest mirror it can find, proxy aware.
- Vanilla or GAPPS, your call. Starts the container service for you.
- Clean uninstall included. GPL-3.0 and on GitHub.
So. Waydroid on your system yet? Or are you still reading the wiki?