Waydroid

Waydroid is an application which uses LXC containers to run Android applications on a non-Android system.

⚠︎

Warning: Waydroid requires a Wayland desktop session and cannot be used on X11 directly, but can be run in a nested Wayland session, using e.g. cage.

⚠︎

Warning: Installing Waydroid on your system before running nixos-generate-config will create unnecessary fstab entries that may interfere with system functionality.

Installation

Enable Waydroid in your system configuration:

❄︎ /etc/nixos/configuration.nix

{
  virtualisation.waydroid.enable = true;
}

After rebuilding and switching, finish the Waydroid install in your shell.

Fetch Waydroid images.
You can add the parameters "-s GAPPS -f" to have GApps support.
$ sudo waydroid init

How to certify a waydroid device for GAPPS[1]

Before the following steps, you might need to do some GPU adjustments. See the troubleshooting section.

Usage

Start the container

Start the Waydroid LXC container
$ sudo systemctl start waydroid-container

You'll know it worked by checking the journal You should see "Started Waydroid Container".
$ sudo journalctl -u waydroid-container -e

Start Waydroid session
You'll know it is finished when you see the message "Android with user 0 is ready".
$ waydroid session start

General usage

Start Android UI
$ waydroid show-full-ui

List Android apps
$ waydroid app list

Start an Android app
$ waydroid app launch <application name>

Install an Android app
$ waydroid app install </path/to/app.apk>

Enter the LXC shell
$ sudo waydroid shell

Overrides the full-ui width
$ waydroid prop set persist.waydroid.width 608

Customization

Running applications that differ from the current host architecture via libhoudini or libndk

Run nix shell github:nix-community/NUR#repos.ataraxiasjel.waydroid-script -c sudo waydroid-script

Or, alternatively, add nur.repos.ataraxiasjel.waydroid-script from the NUR to your flake or shell or NixOS environment.systemPackages, or HM home.packages or something like that based on readme and run sudo waydroid-script

In the TUI, select Android 13 > Install > libhoudini (or libndk, which script author claims may be faster on AMD)

Maintenance

Update Android

Use following command to upgrade Android (LineageOS) to a newer version if available

$ sudo waydroid upgrade

Resetting Android Container

⚠︎

Warning: All files of your Android container will be lost

Stop Waydroid container
$ sudo systemctl stop waydroid-container

Removing images and user data
$ sudo rm -r /var/lib/waydroid/* ~/.local/share/waydroid

Tips and tricks

Mount host directories

⚠︎

Warning: Parts of this instruction will only work with the latest waydroid-helper package in NixOS master and will be available with the next release 25.11

Install and configure graphical application waydroid-helper

environment.systemPackages =  [ pkgs.waydroid-helper ];

systemd = {
  packages = [ pkgs.waydroid-helper ];
  services.waydroid-mount.wantedBy = [ "multi-user.target" ];
};

Enable the user service which is also required. Note that this is not persistent and needs to get started after reboot again.

systemctl --user start waydroid-monitor

Now start waydroid-helper application and add a shared directory. As an example, source directory could be /home/myuser/Public and target directory /home/myuser/.local/share/waydroid/data/media/0/NixOS. Ensure that both directories already exist locally. After that you might need to restart the Waydroid container which is also possible with the graphical user interface.

GPS/Location forwarding

First enable geoclue2 and adb daemon on the host

services.geoclue2.enable = true;
programs.adb.enable = true;

Enable location provider in your desktop environment. For Gnome Shell you can do this

gsettings set org.gnome.system.location enabled true

To test and see location

nix shell nixpkgs#geoclue2 -c $(nix eval --raw nixpkgs#geoclue2)/libexec/geoclue-2.0/demos/where-am-i

Get IP address of the Waydroid guest and connect adb to it

waydroid shell ip addr show
adb connect <IP>:5555

Download, initialize and run geobridge script

wget https://gitlab.com/papiris/geobridge/-/raw/main/geobridge.sh
sh geobridge.sh --init

Notification forwarding

To forward notifications from the Waydroid container to the host system, KDE Connect can be used.

On a Gnome-desktop, add following to your system config and enable:

programs.kdeconnect = {
  enable = true;
  package = pkgs.gnomeExtensions.gsconnect;
};

Open the application Extensions and enable Gsconnect plugin there.

Inside the Waydroid container, follow these steps:

• Download and install the KDE Connect app
• Open the app and and start pairing with the host machine
• You'll have to enable access to notifications by clicking on the corresponding entry in the permissions list inside the app
• If you get the system message "Restricted setting / For your security, this setting is currently unavailable", you'll have to enable restricted settings. Go to Android settings app, in the apps list select KDE connect and click in the upper right corner on the three dot menu to Allow restricted settings
• You may have to reboot the Waydroid container for notification forward to work.

Troubleshooting

GPU Adjustments

In case you have an NVIDIA card or an RX 6800 series, you'll need to disable GBM and mesa-drivers:

≡︎ /var/lib/waydroid/waydroid_base.prop

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

Linux 5.18+

Linux 5.18 and later removed ashmem in favor of memfd, so you may need to tell Waydroid (1.2.1 and later) to use the new module:

≡︎ /var/lib/waydroid/waydroid_base.prop

sys.use_memfd=true

Changing keyboard layout

According to an upstream issue, changing the keyboard layout doesn't seem possible at the moment.

Missing UTF-8 support

According to an upstream issue, Android might fail to display special characters correctly.

Waydroid interferes with suspend/hybernation

According to an upstream issue, Waydroid might interfere with suspend or hybernation. You might have to stop the Android session and container to suspend your machine correctly.

Clipboard sharing

Add wl-clipboard to environment.systemPackages.

See Also:

• Waydroid article on the Archlinux Wiki