Waydroid is a container-based approach to boot a full Android system on a regular GNU/Linux system.
The requirements depend on the CPU architecture. You can check table for more information.
You can check if you have the required CPU instructions with
Waydroid currently works best with Intel GPUs. They should work out of the box.
AMD GPUs appear to have mixed results (in particular, the RX 6800 does not work); if Waydroid does not work you might also want to try the NVIDIA instructions below.
NVIDIA GPUs do not work currently, but there are 2 workarounds:
- Switch to integrated graphic card if possible;
- Use software rendering:
- Make sure that you have already run
waydroid init(see #Installation section)
- Make sure that you have already run
- Restart the
- Restart the
Wayland session manager
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.
You need to run a kernel which comes with the ashmem and binder modules. They are not part of Arch Linux's default kernel (), thus you need to install a kernel which ships these modules.
You might also need to configure your bootloader to use a different kernel. Please refer to the wiki page of your bootloader how to boot with the new kernel. Booting into another kernel (version) is one of the few occasions when you have to reboot a Linux system. You should boot into the kernel with these modules before starting Waydroid.
To get a compatible kernel, you have multiple options:
Thekernel includes the necessary modules. This might be the most comfortable way, as you do not have to compile the kernel (which takes a long time) and will receive updated versions regularly.
You can installAUR and load kernel modules with:
sudo modprobe ashmem_linux binder_linux
Building a kernel
Alternatively, you can recompile the Kernel#Compilation.kernel — or other kernel packages (>=5.7) — with the necessary options. Also see
When setting compilation options, you have 2 options available; binder and binderfs. Instructions for both are provided below.
The modules can either be compiled into the kernel (
y), into modules (
m), or not at all (
n). Also, not all combinations in the configuration are possible, and some options will require other options.
The configuration options below will compile ashmem and binder as modules, while the last option specifies that there will be three devices created in the
/dev/ directory, when the binder module is loaded.
CONFIG_ASHMEM=m CONFIG_ANDROID=y CONFIG_ANDROID_BINDER_IPC=m CONFIG_ANDROID_BINDERFS=n CONFIG_ANDROID_BINDER_DEVICES="binder,hwbinder,vndbinder"
When building a kernel from the AUR, one can update the configuration with the following steps:
makepkg --nobuild, which will download the sources, verify and extract them and run the
- edit the
.configfile (with the dot in the filename), which is located at the base of the kernel directory.
- at the end of the
prepare()function was probably a command which regenerates the makefiles with information from the configuration, possibly
make olddefconfig. Move that to the
build()function, or execute it yourself.
makepkg --noextract, which will continue from the place where
The binder kernel module is known to cause some issues to several users. To address these issues, binderfs was created. One has to choose between the old and the new way when compiling the kernel. With the options below, one will use binderfs instead.
With the kernel sources comes also a simple script to set configuration options. It will not do dependency checks, just like when editing the configuration by hand. When being in the same directory where the
.config file lies, one can execute the following commands:
scripts/config --module CONFIG_ASHMEM scripts/config --enable CONFIG_ANDROID scripts/config --enable CONFIG_ANDROID_BINDER_IPC scripts/config --enable CONFIG_ANDROID_BINDERFS scripts/config --set-str CONFIG_ANDROID_BINDER_DEVICES ""
When building a kernel from the AUR, it is enough to insert these lines at the right place in the PKGBUILD, usually in
Setup binder devices
Make sure you have the latest version of Waydroid package, and Waydroid will take automatically care of this.
Install the AUR package.
Afterwards init Waydroid, this will automatically download the latest Android image.
# waydroid init
Next start/enable the
Waydroid should now work.
Make sure that
waydroid-container.service is running then run:
$ waydroid session start
The Waydroid session is now active, here are a couple of useful commands to interact with it:
$ waydroid show-full-ui
# waydroid shell
Install an application:
$ waydroid app install $path_to_apk
Run an application:
$ waydroid app launch $package-name #Can be retrieved with `waydroid app list`
The network should work out of the box, if its not you might need to allow the following rules through your firewall before running Waydroid session start.
Takingas 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 run into issues, take a look at the official Issue Tracker: Waydroid issue tracker
Waydroid is in rapid developement so if you face issues, here is a good list of steps to do first:
- Make sure your Waydroid package is up to date;
- Make sure you have the latest Waydroid image by running
# waydroid upgrade;
- Reset Waydroid: stop the
# waydroid init -fand start the service again.
Rotated apps are unusable
Click F11 to switch the current app to windowed mode.
Failed to start Clipboard manager service
Sometimes the physical keyboard does not work
Press Left Alt key.
Commands inside Waydroid shell outputs inaccessible or not found
On Arch based distributions there's a "bug" that may appear while working with lxc-attach that may cause this issue with commands inside
waydroid shell like
A possible workaround for this would be replace the
# waydroid shell command with
# lxc-attach -P /var/lib/waydroid/lxc/ -n waydroid --clear-env.
WARNING: Service manager /dev/binder has died
You should enable PSI.
psi=1 to kernel command line.