Ultimate Guide to install Waydroid in any Arch-based distro(especially Garuda)

WAYDROID, formerly referred to as Anbox-Halium, is a rebuild of Anbox, intended to use more of the native host’s hardware, resulting in faster performance than Anbox.

And yes, ARM apps/games work just fine!!

Waydroid - ArchWiki (Please have a look into the ArchWiki for additional information)


Some of you would be able to follow the above guides and get Waydroid running, but you might probably get stuck somewhere and find it all confusing, just like it was for me before getting it running.
I have made this guide so that it would be a lot easier for you to get Waydroid running!

These steps should work for everyone, and I have ensured every step is explained well enough so that even someone new to Linux can do it!

Supported Hardware
I) Supported CPUs :
Waydroid supports most common architectures (ARM, ARM64, x86 & x86_64 CPUs).

II) Supported GPUs :
Waydroid uses Android's mesa integration for passthrough, and that enables support to most ARM/ARM64 SOCs on the mobile side, and Intel/AMD GPUs for the PC side. For Nvidia GPUs (except tegra) and VMs, we recommend using software-rendering (check out the link for steps to force Waydroid to run without GPU acceleration).

[If you have Nvidia dedicated GPU and an integrated AMD/Intel GPU, you can choose to pass Waydroid graphics only through your integrated one.
The Waydroid-Settings app mentioned in point 10 of this guide can be used to do this easily.]

1. Wayland:
First of all, you need Wayland.
Waydroid only works in a Wayland session manager, so make sure you are in a Wayland session.
Note that even if you are in X11, many Wayland session manager supports nested session (so you can run it inside your X11 session); the simplest example is weston.

2. Kernel with required modules:

2.1 You need to run a kernel which comes with the binder modules.
The following kernels include the necessary kernel modules with them:

I) linux-zen
(Garuda's default kernel)

II) The Cachyos kernels:
(available in the chaotic-aur)

  • linux-bore
  • linux-tt

III) linux-xanmod
(available in the chaotic-aur)

[ Enable PSI by default with Xanmod kernel:
Add psi=1 boot parameter to the kernel command line of your boot loader.
(For Grub: edit /etc/default/grub and add psi=1 to the end of GRUB_CMDLINE_LINUX_DEFAULT, within "" and before any # symbols)

Install any one of these kernels by:

  • GUI approach:

    Garuda Settings Manager (App) -> Hardware -> Kernel

  • CLI approach:

    Run this command in the terminal (replacing *** with the kernel name, like bore, xanmod)
    sudo pacman -S linux-*** linux-***-headers


2.1 Install binder_linux-dkms, which provides binder_linux.

(i) sudo pacman -S binder_linux-dkms

This installs the required binder modules if a kernel doesn't include them with it, like Arch Linux's default kernel (or any other kernel)

(check out the above hyperlink link for more information, recent updates and prevailing issues, if any, regarding binder modules)

Install binder_linux-dkms, only if your kernel doesn't have binder modules inbuilt.

You can check by using the modprobe command:
(The binder module is present by the name binder or binder_linux)

sudo modprobe -a binder or sudo modprobe -a binder_linux

If either of the above command returns a blank output, your kernel already has the binder modules inbuilt.

3. Setting up Kernel Modules

You probably won't require this step as of now. It was required for earlier versions. You may take a look to have an idea of how it works under the hood.

i) To automatically load the binder modules on boot(Kernel module - ArchWiki):
Create a file inside /etc/modules-load.d/, which contains the lines:
(sudo nano /etc/modules-load.d/waydroid.conf)


  • ( it could be simply binder instead of binder_linux depending on the output of modprobe command as used above)

(Save and exit)

ii) To automatically create a mount point for the binder modules at boot
(systemd - ArchWiki):
Create a file in /etc/tmpfiles.d/ with the content:
(sudo nano /etc/tmpfiles.d/waydroid.conf)


d! /dev/binderfs 0755 root root

(Save and exit)

iii) To automatically mount the binder modules on boot, add a line in the fstab. Using the option nofail here will not greet you with a recovery shell when you are booting a kernel without binderfs support (such as the standard kernel):
(sudo nano /etc/fstab)


none                         /dev/binderfs binder   nofail  0      0

(Save and exit)

You can skip the iv) step if you reboot after the iii) one.

iv) Mount the binder modules:
Load the binder modules (Kernel module - ArchWiki)
(mkdir(1) — Arch manual pages)
(mount(8) — Arch manual pages)

  • sudo modprobe -a binder_linux

(it could be simply binder instead of binder_linux)

  • sudo mkdir -p /dev/binderfs
  • sudo mount -t binder none /dev/binderfs

4. Installing Waydroid:
(available in chaotic-aur for Garuda users):

sudo pacman -Syu waydroid  

Now reboot!

5. Setting up Waydroid:

After you have installed Waydroid

5.1 Initialize Waydroid:
sudo waydroid init

(You might have to reboot again.)

Here is a breakdown of what the waydroid init command does:

  • Downloads the latest Android image from the Waydroid repository.
  • Sets up the Waydroid configuration file. This file specifies the location of the Android image, the Waydroid runtime environment, and other settings.
  • Starts the Waydroid container.

[The download speeds may be very slow during the initialization process when you download the container images, you can try connecting to a European country through a VPN(Several people have encountered this issue). You can check out Riseup-VPN in the chaotic-aur or its snap version]

5.2 Enable and start the waydroid-container service:

sudo systemctl enable --now waydroid-container

Then launch Waydroid from the applications menu.


5.2 To start Waydroid without systemctl, you need to follow a few simple steps:

i. Start the container first:

sudo waydroid container start

ii. And in a new terminal tab, start the waydroid session (without sudo):

waydroid session start

After that starts and you see "Android with user 0 is ready", it is safe to launch an app from the applications menu.

  • To Launch Waydroid In Full-Screen Mode from the terminal:

waydroid show-full-ui

6. To Install an application:

waydroid app install $path_to_apk

7. Install ARM translation libraries and App Stores

We have an AUR package for waydroid-script-git and it is also in our chaotic-aur.

I) Install it by:
sudo pacman -S waydroid-script-git

II) Run sudo waydroid-extras in the terminal to get an interactive terminal interface.
(Check your Android version from the 'About phone' section in the settings app.)

Install gapps & libndk/libhoudini to install Google Play Store and translation libraries to run ARM-only apps.

libndk_translation from Chromiumos' guybrush firmware seems to have better performance than libhoudini on AMD.
Whereas, libhoudini is Intel's ARM translation library for Intel/AMD x86 CPU, pulled from Microsoft's WSA 11 image, so it should work better on Intel than libndk.

I tested on my AMD hardware and experienced frame drops and touch input issues when I ran 'Angry Birds' with libhoudini. Running it with just libndk worked just fine.

If you install both libndk & libhoudini, apps will use the ARM-translation library you last installed(the last one you installed overwrites the previous one), so it is of no use. (That's what I saw when I tested)

[ You can check out other software from waydroid-extras as well,

  • Open GApps: an open-source effort to script the automatic generation of up-to-date Google Apps packages

  • libhoudini & libndk: arm translation libraries

  • Magisk Delta: a suite of open-source software for customizing Android
    (Magisk only works with Xanmod kernel)

You may refer to these for further details to install Magisk on Waydroid:


Other ways to install GApps,
i. From the chaotic-aur,
sudo pacman -S waydroid-image-gapps
ii. From waydroid itself,
sudo waydroid init -s GAPPS -f
(restart the waydroid-container to see the effect)

III) To get gapps working you need to register your waydroid device with Google.
Run sudo waydroid-extras, and select Get Google Device ID to Get Certified option, when the waydroid session has finished booting, copy the returned numeric ID open "https://google.com/android/uncertified/?pli=1" enter the id and register it, you may need to wait up to 10-20 minutes for device to get registered, then clear Google Play Service's cache and try logging in!

Another way to register your device without the waydroid-script

i. Enter the Waydroid Shell,

sudo waydroid shell

ii. Run the following command,

ANDROID_RUNTIME_ROOT=/apex/com.android.runtime ANDROID_DATA=/data ANDROID_TZDATA_ROOT=/apex/com.android.tzdata ANDROID_I18N_ROOT=/apex/com.android.i18n sqlite3 /data/data/com.google.android.gsf/databases/gservices.db "select * from main where name = \"android_id\";"

You will get an output similar to this:


iii. Go to https://www.google.com/android/uncertified/, and enter your android_id to Register your device!

IV) Check out these open-source alternatives for Google's PlayStore:

If you can't find or install any of the apps from the Play Store, you should be able to install them from the Aurora Store.

*To run Roblox:

[ You need to do some tweaks (this might also be useful to run some other games)]

Edit /var/lib/waydroid/waydroid_base.prop and change ro.hardware.gralloc=gbm to ro.hardware.gralloc=minigbm_gbm_mesa.

(This guide in itself is an almost complete guide for Waydroid!)

8. To fix unusable rotated apps:

Run this in your normal terminal while Waydroid is running:

sudo waydroid shell wm set-fix-to-user-rotation enabled

9. Root Access in Waydroid!:

(I) Install Magisk (As of now only works with Xanmod kernel):

You can install it using the waydroid-extras software as mentioned in step 7 of this guide.

(II) Install Shizuku (Works with all kernels):

You can install it from Play Store or F-Droid

Although Shizuku does not give you a full Root Access, it can give 'root-required apps' adb permissions in Android, which is more than sufficient for about 99% of root-required apps.

You will need to establish adb connection between Shizuku and your device every time you start a new Waydroid session in order to grant apps adb permissions.
You can do this from your Linux host terminal itself. Just run this command after the Waydroid UI has launched:

sudo waydroid shell sh /storage/emulated/0/Android/data/moe.shizuku.privileged.api/start.sh

This would have been a more convoluted process on an Android device.
But, with Waydroid on a Linux host, you can make it easier by automating this every time you start your Waydroid session.

Now, to automate this, create a permanent alias (How to create an alias?) for,

 waydroid show-full-ui & sleep 10 && pkexec waydroid shell sh /storage/emulated/0/Android/data/moe.shizuku.privileged.api/start.sh

You would need to wait for the Waydroid session to start before you run the moe.shizuku.privileged.api/start.sh script. So replace the numeric value (in seconds) in sleep 10 considering the time it normally takes for Waydroid UI to launch on your system.
(I have a 2021 processor, and it launches Waydroid UI within 10 seconds; it would be normal for a 2017 processor to take a minute to launch Waydroid UI)

Details of the alias created
  • & operator is used to run a command in the background, which means that the command will continue to run even after the terminal session is closed.
  • && is used when you want to execute a command only if the previous command succeeded.
  • You can access polkit using pkexec.


You can run this alias to start your Waydroid Session and automatically establish adb connection between Shizuku & Waydroid.

KDE Plasma users can use kdesu instead of pkexec. With the added benefit that kdesu can remember your password (this persists across reboots), you would only have to enter your password once.

If you want to create a .desktop file for this, check out this comment posted below.

10. Install a Key Mapper
Using these apps, you can map your keyboard keys for different actions in games, apps or even as keyboard shortcuts!

(I) GitHub - Xtr126/XtMapper: Keymapper for Android x86
Download the APK from the GitHub releases.

(II) Key Mapper | F-Droid - Free and Open Source Android App Repository
You can also find it in Play Store.

[YouTube: How to use Key Mapper?
You can check out this video to get an idea of how it works.]

I could get touch inputs of games like Need for Speed: No Limits mapped to my keyboard perfectly!
And there is also no input lag with the keyboard!

11. You can install Waydroid-Settings (a GTK app written in Python to control Waydroid settings):


You can now have a look here for guides like Setting up a shared folder & Setting up Waydroid only Sessions!

13. To upgrade Waydroid images, run:
sudo waydroid upgrade


(You should check out the above link for some handy troubleshooting tips.)

(I) If you encounter, [gbinder] WARNING: Service manager /dev/binder has died,

Enable PSI by default:
Add psi=1 boot parameter to the kernel command line of your boot loader.
(For Grub: edit /etc/default/grub and add psi=1 to the end of GRUB_CMDLINE_LINUX_DEFAULT, within "" and before any # symbols)

(II) If you are not able to run Waydroid (i.e. getting errors) when you switch to another kernel (that has the binder drivers) or even to Arch's stock kernel + binder_linux-dkms, reinitialize Waydroid and reboot,

sudo waydroid init -f
sudo waydroid init -s GAPPS -f (If you have a GAPPS image)

The waydroid init -f command initializes Waydroid.
( The -f flag tells Waydroid to force a reset.)

This downloads the latest Android image (if there is an update), sets up the Waydroid configuration file and starts the Waydroid container.

Check out the comments below for more information regarding recent updates, hacks, related tools and prevailing issues.

Feel free to share your experience using waydroid and all the apps and games you got working.


Does the guidance on the Arch wiki page not work?


1 Like

Some instructions are lacking in the Arch wiki, specifically regarding the automatic mounting of binderfs on boot, which is where most people get stuck.

Rest, everything is well documented in the Arch wiki

1 Like

Thank you, @Austin, Have you tested this procedure, and what were your personal results? Any further hints?

Feliz Ano Nuevo!


Happy New Year @Bro!

I have well tested this procedure, and I have covered every issue I was facing while doing so, and I have Waydroid up and running:


I am able to launch waydroid fine, but it will not connect to wifi. Wifi is disabled by default and enabling it in settings does nothing, then after a little bit disables itself again.

I'm not sure where I can find logs for this or see the reason. I ran the ufw commands in the arch wiki, but I'm not sure they did anything. Is ufw the firewall Garuda (KDE Dragonized) uses?

Well, ufw is a tool for managing firewalls, and there are other tools as well,

for example, firewalld, which is I think is the default one for Garuda.

In the Arch wiki, they have taken ufw as an example:

Taking ufw as an example:

  • Dns traffic needs to be allowed:
    • # ufw allow 67
    • # ufw allow 53
  • Packet forwarding needs to be allowed:
    • # ufw default allow FORWARD

If you know the firewalld equivalent of the above, you can apply them or switch from firewalld to ufw:


sudo pacman -Rns firewalld
sudo pacman -S ufw
sudo ufw enable

If someone knows the equivalent of firewalld of the above instructions, please do share it in this thread

I hope the solves the issue.

Recently Waydroid has started to freeze the entire system on running it and I have to do a force reboot.

Is anyone else facing this issue?

My logs:

(493643) [09:06:06] % mkdir -p /var/lib/waydroid/lxc/waydroid
(493643) [09:06:06] % cp -fpr /usr/lib/waydroid/data/configs/config_2 /var/lib/waydroid/lxc/waydroid/config
(493643) [09:06:06] % sed -i s/LXCARCH/x86_64/ /var/lib/waydroid/lxc/waydroid/config
(493643) [09:06:06] % mv /var/lib/waydroid/config_nodes /var/lib/waydroid/lxc/waydroid
(499570) [09:08:10] % chmod 666 -R /dev/binder
(499570) [09:08:10] % chmod 666 -R /dev/vndbinder
(499570) [09:08:10] % chmod 666 -R /dev/hwbinder
(499570) [09:08:10] Container manager is waiting for session to load
(499594) [09:08:24] Starting waydroid session
(499594) [09:08:24] Save session config: /var/lib/waydroid/session.cfg
(499594) [09:08:24] UserMonitor service is not even started
(499594) [09:08:24] Clipboard service is not even started
(499594) [09:10:05] waydroidusermonitor: Received transaction: 1
(499594) [09:10:05] Android with user 0 is ready
(000581) [09:13:18] % mkdir -p /dev/binderfs
(000581) [09:13:18] % mount -t binder binder /dev/binderfs
(000581) [09:13:18] % ln -s /dev/binderfs/anbox-hwbinder /dev/binderfs/anbox-vndbinder /dev/binderfs/anbox-binder /dev/binderfs/features /dev/binderfs/vndbinder /dev/binderfs/hwbinder /dev/binderfs/binder /dev/binderfs/binder-control /dev/
(000581) [09:13:18] % chmod 666 -R /dev/binder
(000581) [09:13:18] % chmod 666 -R /dev/vndbinder
(000581) [09:13:18] % chmod 666 -R /dev/hwbinder
(000581) [09:13:18] Found session config on state: RUNNING, restart session
(000581) [09:13:18] Container manager is waiting for session to load
(033944) [09:21:03] % tail -n 60 -F /var/lib/waydroid/waydroid.log
(033944) [09:21:03] *** output passed to waydroid stdout, not to this log ***

hi im getting this eror while trying to start waydroid container saying
XDG session is not wayland. how do i change my session to wayland? im on garuda cinnamon edition. tnx in advance.

I think cinnamon doesn't currently support, you would have to use kde or gnome.

Check out weston

ok tnx ima try weston

i couldn't get it working can you tell me what version of garuda your in?

There is no versioning of Garuda, it's a rolling distro

I will check it when I get time

1 Like

i meant are you using kde or xfce what desktop enviroment are you using soory for bothering you.


I am using KDE, which already has a Wayland session.

1 Like

When you get this error first ensure this command is already running on a different tab of the terminal sudo waydroid container start. Then on your current tab fire up Weston, then at the top left side of the Weston window you'll see an icon to launch a terminal within Weston. So go ahead and launch and type this command, kwin_wayland "waydroid session start" Now here's a tip, just let the command simmer for around 10 mins, so that the droid can come to life. I should mention I have tried this on Garuda KDE. Cheers!

So I'm trying to make it work on a KDE Wayland session. 1st console I run:

  1. sudo systemctl start waydroid-container
    it is running

2. sudo waydroid container start
it stays black, like is loading something

so I open a 2nd konsole and run
3. waydroid session start

Are you suggesting me @general_zod to wait for 10 minutes the 1st konsole in the step 2 to give me some output instead of going for a 2nd konsole?
I have a 3rd konsole running waydroid log to debug this somehow because I can't simply make it work.
When I try in a 3rd konsole waydroid show-full-ui I get no results too.

EDIT: Just read their documentation and it's not compatible with NVIDIA cards. I guess that was my problem after all.

1 Like

not quite right buddy,

  1. once you run sudo waydroid container start,

  2. Launch a second terminal and type weston then hit enter, you may need to install weston if you haven't yet done so already.

  3. Once weston is up and running, find a terminal icon at the top left side of the weston compositor, launch that terminal then type kwin_wayland "waydroid session start" and let your android boot up and that usually takes about 10 minutes give or take.

N.B: If you try to run waydroid session start and you're in KDE you're more than likely to receive the error, XDG Session is not "wayland" this is because WAYdroid natively supports the WAYland compositor found in Gnome, and so as a work around we use weston in KDE as a reference implementation, of a Wayland Compositor.

@general_zod I'm running a KDE Wayland Session. Wouldn't that be enough instead of Weston?

This topic was automatically closed 14 days after the last reply. New replies are no longer allowed.