diff --git a/_posts/2026-02-15-archlinux-waydroid-installation-guide.md b/_posts/2026-02-15-archlinux-waydroid-installation-guide.md new file mode 100644 index 0000000..7ae7841 --- /dev/null +++ b/_posts/2026-02-15-archlinux-waydroid-installation-guide.md @@ -0,0 +1,182 @@ +--- +layout: post +author: Sam Hadow +tags: archlinux sysadmin +--- + +This blog post is a short guide to run and use [waydroid](https://github.com/waydroid/waydroid) on archlinux. + +# What is waydroid? + +Waydroid is a container-based approach to boot a ful android system on a regular linux system with an x86 or ARM CPU, and so has less overhead than an android x86 virtual machine to run android apps on a linux system. Waydroid only works in a wayland session but it's still possible to use a nested session if you use X11, which will be covered in this guide. + +# Installation guide + +## Requirements + +A kernel which comes with the `rust_binder` module is necessary to run waydroid, `linux-zen` kernel includes this module. + +### Other kernels + +If you're using another kernel you can add it via DKMS (note that you can use another [aur helper](https://wiki.archlinux.org/title/AUR_helpers) than yay). + +```bash +yay -S binder_linux-dkms +``` + +Then you can manually load it: + +```bash +sudo modprobe binder-linux devices=binder,hwbinder,vndbinder +``` + +Or load it automatically at boot: + +```bash +echo "binder_linux" > /etc/modules-load.d/binder_linux.conf +echo "options binder_linux devices=binder,hwbinder,vndbinder" > /etc/modprobe.d/binder_linux.conf +``` + +## Installing necessary packages: + +```bash +sudo pacman -S waydroid +``` + +### [On X11] + +If using X11, you'll need to run a nested wayland session, a simple solution is using cage. You could also use weston. + +```bash +sudo pacman -S cage +``` + +## Initializing waydroid: + +```bash +sudo waydroid init +``` + +Or with google apps support: + +```bash +sudo waydroid init -s GAPPS +``` + +## Running waydroid + +This command will automatically start the waydroid container and a session before showing the UI. + +```bash +waydroid show-full-ui +``` + +Otherwise if you want a CLI, you have to start the container and then a session: + +```bash +sudo systemctl start waydroid-container.service +waydroid session start +``` + +#### Useful commands + +| Command | Purpose | +| :---------------------------------- | :----------------------------- | +| `waydroid session start` | Starting a session | +| `waydroid session stop` | Stopping a session | +| `waydroid status` | Checking Waydroid status | +| `sudo waydroid upgrade` | Upgrading the LineageOS image | +| `waydroid app list` | Get the list of installed apps | +| `waydroid app install $path_to_apk` | Install an APK | +| `waydroid show-full-ui` | Launch the GUI | +| `waydroid app launch $package_name` | Launch an app | +| `sudo waydroid shell` | Launch a shell | +| `waydroid --help` | Display the help message | +| + +### [On X11] + +On X11 waydroid container can be started but then all waydroid commands need to be run inside a nested wayland session. +If you just need waydroid UI the simplest is with cage: + +```bash +cage -- waydroid show-full-ui +``` + +If you need the command line then you need to have a console running inside a wayland session. For example with Konsole: + +```bash +cage -- konsole +``` + +You can then type the commands the same as described above. + +## Firewall rules and packet forwarding + +You need some additional rules in your firewall if you want the network to work inside waydroid. For example with nftables you need these additional rules in your tables: + +``` +table inet filter { + chain input { + # -------------------------------- waydroid + iifname "waydroid0" accept comment "Allow incoming network traffic from WayDroid" + + } + + chain forward { + # -------------------------------- waydroid + iifname "waydroid0" accept comment "Allow incomming network traffic from WayDroid" + oifname "waydroid0" accept comment "Allow outgoing network traffic from WayDroid" + } + chain output { + } +} + +``` + +You also need to enable packet forwarding. To check if it's already enabled: + +```bash +sysctl net.ipv4.ip_forward +sysctl net.ipv6.conf.all.forwarding +``` + +If it's not enabled you can permanently enable it in the file `/etc/sysctl.conf` by uncommenting the lines `net.ipv4.ip_forward=1` for IPv4 and `net.ipv6.conf.all.forwarding=1` for IPv6. Please note that in most cases you can for now just enable the IPv4 packet forwarding and ignore the IPv6 one. +And to reload the configuration: + +```bash +sudo sysctl -p /etc/sysctl.conf +``` + +## Additional notes + +#### 1) clipboard sharing + +If you want to share the clipboard between a wayland session and waydroid UI you need to install the packages `python-pyclip` and `wl-clipboard`. +It however won't work with X11 and nested wayland sessions. + +#### 2) app stores + +You might want to install [aurora store](https://gitlab.com/AuroraOSS/AuroraStore), an open source google play store client not requiring a google account. And an F-Droid client like [droidify](https://f-droid.org/en/packages/com.looker.droidify/). + +#### 3) GPU + +If you have an Intel or AMD GPU it should work out of the box. But if you have a NVIDIA GPU you'll need to enable software rendering. For that in `/var/lib/waydroid/waydroid.cfg` add the following: + +``` +[properties] +ro.hardware.gralloc=default +ro.hardware.egl=swiftshader +``` + +and then run: + +```bash +sudo waydroid upgrade --offline +sudo systemctl restart waydroid-container.service +``` + +#### 4) Additional troubleshooting + +Finally you might want to check the [archwiki](https://wiki.archlinux.org/title/Waydroid) directly if having issues with waydroid. +And although it's quite old and contains some unecessary steps now, you can check [this guide](https://forum.garudalinux.org/t/ultimate-guide-to-install-waydroid-in-any-arch-based-distro-especially-garuda/15902) too.