Packages Forums Wiki Bugs Security AUR Download

Create account

Page Discussion Read More

Waydroid
This article or section needs language, Related articles
wiki syntax or style improvements. See
Anbox
Help:Style for reference.
Linux Containers
Reason: Need to improve style. (Discuss in
Talk:Waydroid)

Waydroid is a container­based approach to boot a full Android system on a regular GNU/Linux system.

Contents [hide]
1 Prerequisites
1.1 CPU Requirements
1.2 GPU Requirements
1.3 Wayland session manager
1.4 Kernel Modules
1.4.1 Using Linux­Zen
1.4.2 DKMS modules
1.4.3 Building a kernel
1.4.3.1 Using binder
1.4.3.2 Using binderfs
1.4.4 Setup binder devices
2 Installation
3 Usage
4 Network
5 Troubleshooting
5.1 General tips
5.2 Rotated apps are unusable
5.3 Failed to start Clipboard manager service
5.4 Sometimes the physical keyboard does not work
5.5 Commands inside Waydroid shell outputs inaccessible or not found
5.6 WARNING: Service manager /dev/binder has died
6 See also

Prerequisites
CPU Requirements
CPU Requirements
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  cat /proc/cpuinfo .

GPU Requirements
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)
Edit  /var/lib/waydroid/waydroid_base.prop  and set:

ro.hardware.gralloc=default 
ro.hardware.egl=swiftshader

Restart the  waydroid‐container.service .

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 managers support nested session (so you can
run it inside your X11 session), the simplest example is weston.

Kernel Modules
You need to run a kernel which comes with the ashmem and binder modules. They are not part of Arch
Linux's default kernel (linux), 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:

Using Linux­Zen

The linux‐zen kernel 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.

DKMS modules

You can install anbox‐modules‐dkmsAUR and load kernel modules with:

# modprobe ashmem_linux 
# modprobe binder_linux 
Building a kernel

Alternatively, you can recompile the linux kernel — or other kernel packages (>=5.7) — with the
necessary options. Also see Kernel#Compilation.

When setting compilation options, you have 2 options available; binder and binderfs. Instructions for both
are provided below.

Using binder

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:

1. run  makepkg ‐‐nobuild , which will download the sources, verify and extract them and run the 

prepare()  function.
2. edit the  .config  file (with the dot in the filename), which is located at the base of the kernel
directory.
3. 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.
4. run  makepkg ‐‐noextract , which will continue from the place where  makepkg ‐‐nobuild
stopped.

Using binderfs

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  prepare() .

Setup binder devices

Make sure you have the latest version of Waydroid package, and Waydroid will take automatically care of
this.

Installation
Install the waydroidAUR package.

Optionally, install waydroid‐imageAUR or waydroid‐image‐gappsAUR to provide the needed Android image
through AUR.

Afterwards init Waydroid, this will automatically download the latest Android image if it is not yet available.

# waydroid init 

To init with GApps support:

# waydroid init ‐s GAPPS ‐f 

Next start/enable the  waydroid‐container.service .

Waydroid should now work.

Usage
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:

Launch GUI:

$ waydroid show‐full‐ui 

Launch shell:

# waydroid shell 

Install an application:

$ waydroid app install $path_to_apk 

Run an application:
Run an application:

$ waydroid app launch $package‐name #Can be retrieved with `waydroid app list` 

Network
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.

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

Troubleshooting
If you run into issues, take a look at the official Issue Tracker: Waydroid issue tracker

General tips
Waydroid is in rapid developement so if you face issues, here is a good list of steps to do first:

1. Make sure your Waydroid package is up to date;
2. Make sure you have the latest Waydroid image by running

# waydroid upgrade

3. Reset Waydroid: stop the  waydroid‐container.service , run

# waydroid init ‐f

and start the service again.
4. You may also want to do little cleanup, run

# rm ‐rf /var/lib/waydroid /home/.waydroid

$ rm ‐rf ~/waydroid ~/.share/waydroid ~/.local/share/applications/*aydroid* 
~/.local/share/waydroid

Rotated apps are unusable
See https://github.com/waydroid/waydroid/issues/70

Click F11 to switch the current app to windowed mode.
Failed to start Clipboard manager service
Install python‐pyclipAUR

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  adbd  or  settings .

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
See https://github.com/waydroid/waydroid/issues/136

You should enable PSI . Add  psi=1  to the kernel command line.

See also
Waydroid GitHub repo
Waydroid documentation
Waydroid Matrix group
Waydroid Telegram group

Categories:  Sandboxing Virtualization Android

This page was last edited on 25 June 2022, at 12:41.

Content is available under GNU Free Documentation License 1.3 or later unless otherwise noted.

Privacy policy About ArchWiki Disclaimers