Language: English | 中文 | Русский

Waydroid Helper is a graphical user interface application written in Python using PyGObject. It provides a user-friendly way to configure Waydroid and install extensions, including Magisk and ARM translation.

• Configure Waydroid settings
• Key Mapper: Keyboard and mouse mapping for Android apps and games
  • Multiple control widgets (buttons, directional pad, aim controls, macros)
  • Customizable key bindings and layouts
  • Support for complex gaming scenarios (FPS, MOBA)
  • See the Key Mapping Guide for detailed instructions
• Install extensions for Waydroid
  • Magisk
  • Magisk
  • libhoudini
  • libndk
  • OpenGapps
  • MindTheGapps
  • MicroG
  • SmartDock

For Arch users, Waydroid Helper is available in the AUR:

yay -S waydroid-helper

echo 'deb http://download.opensuse.org/repositories/home:/CuteNeko:/waydroid-helper/Debian_Unstable/ /' | sudo tee /etc/apt/sources.list.d/home:CuteNeko:waydroid-helper.list
curl -fsSL https://download.opensuse.org/repositories/home:CuteNeko:waydroid-helper/Debian_Unstable/Release.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/home_CuteNeko_waydroid-helper.gpg > /dev/null
echo -e "Package: python3-pywayland\nPin: origin \"download.opensuse.org\"\nPin-Priority: 1001" | sudo tee /etc/apt/preferences.d/99-pywayland.pref
sudo apt update
sudo apt install waydroid-helper

echo 'deb http://download.opensuse.org/repositories/home:/CuteNeko:/waydroid-helper/Debian_Testing/ /' | sudo tee /etc/apt/sources.list.d/home:CuteNeko:waydroid-helper.list
curl -fsSL https://download.opensuse.org/repositories/home:CuteNeko:waydroid-helper/Debian_Testing/Release.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/home_CuteNeko_waydroid-helper.gpg > /dev/null
echo -e "Package: python3-pywayland\nPin: origin \"download.opensuse.org\"\nPin-Priority: 1001" | sudo tee /etc/apt/preferences.d/99-pywayland.pref
sudo apt update
sudo apt install waydroid-helper

echo 'deb http://download.opensuse.org/repositories/home:/CuteNeko:/waydroid-helper/Debian_12/ /' | sudo tee /etc/apt/sources.list.d/home:CuteNeko:waydroid-helper.list
curl -fsSL https://download.opensuse.org/repositories/home:CuteNeko:waydroid-helper/Debian_12/Release.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/home_CuteNeko_waydroid-helper.gpg > /dev/null
echo -e "Package: python3-pywayland\nPin: origin \"download.opensuse.org\"\nPin-Priority: 1001" | sudo tee /etc/apt/preferences.d/99-pywayland.pref
sudo apt update
sudo apt install waydroid-helper

echo 'deb http://download.opensuse.org/repositories/home:/CuteNeko:/waydroid-helper/Debian_13/ /' | sudo tee /etc/apt/sources.list.d/home:CuteNeko:waydroid-helper.list
curl -fsSL https://download.opensuse.org/repositories/home:CuteNeko:waydroid-helper/Debian_13/Release.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/home_CuteNeko_waydroid-helper.gpg > /dev/null
echo -e "Package: python3-pywayland\nPin: origin \"download.opensuse.org\"\nPin-Priority: 1001" | sudo tee /etc/apt/preferences.d/99-pywayland.pref
sudo apt update
sudo apt install waydroid-helper

sudo dnf copr enable cuteneko/waydroid-helper
sudo dnf install waydroid-helper

sudo add-apt-repository ppa:ichigo666/ppa
echo -e "Package: python3-pywayland\nPin: origin \"ppa.launchpadcontent.net\"\nPin-Priority: 1001" | sudo tee /etc/apt/preferences.d/99-ichigo666-ppa.pref
sudo apt update
sudo apt install waydroid-helper

1. Go to the releases page
2. Download the appropriate package for your distribution
3. Install the package

For manual installation, you'll need to install the dependencies and build the project using Meson.

1. Install dependencies:

   sudo pacman -S gtk4 libadwaita meson ninja

2. Clone the repository:

   git clone https://github.com/waydroid-helper/waydroid-helper.git
   cd waydroid-helper
   

3. Build and install using Meson:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   meson setup --prefix /usr build
   sudo ninja -C build install
   
   # Uninstall waydroid helper
   # sudo ninja -C build uninstall
   

1. Install dependencies:

   sudo apt install libgtk-4-1 libgtk-4-dev libadwaita-1-dev libadwaita-1-0 libgirepository1.0-dev gcc libcairo2-dev pkg-config python3-dev gir1.2-gtk-4.0 gir1.2-adw-1 gettext ninja-build fakeroot libdbus-1-dev desktop-file-utils software-properties-common -y

2. Clone the repository:

   git clone https://github.com/waydroid-helper/waydroid-helper.git
   cd waydroid-helper
   

3. Build and install using Meson:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install meson
   pip install -r requirements.txt
   meson setup --prefix /usr build
   sudo ninja -C build install
   
   # Uninstall waydroid helper
   # sudo ninja -C build uninstall
   

1. Install dependencies:

   sudo dnf install gtk4 gtk4-devel libadwaita libadwaita-devel gobject-introspection-devel gcc cairo-devel pkgconf-pkg-config python3-devel gobject-introspection gtk4-devel libadwaita-devel gettext ninja-build fakeroot dbus-devel desktop-file-utils -y

2. Clone the repository:

   git clone https://github.com/waydroid-helper/waydroid-helper.git
   cd waydroid-helper
   

3. Build and install using Meson:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install meson
   pip install -r requirements.txt
   meson setup --prefix /usr build
   sudo ninja -C build install
   
   # Uninstall waydroid helper
   # sudo ninja -C build uninstall
   

• Key Mapping Guide: Comprehensive guide for using the key mapping system to control Android apps and games with keyboard and mouse

Enable systemd service

systemctl --user enable waydroid-monitor.service --now
sudo systemctl enable waydroid-mount.service --now

For AppImage users, you need to manually copy the D-Bus configuration files and systemd unit files to their respective system locations to enable proper functionality. Here's the suggested file structure:

usr
├── lib
│   └── systemd
│       ├── system
│       │   └── waydroid-mount.service
│       └── user
│           └── waydroid-monitor.service
└── share
    ├── dbus-1
    │   ├── system.d
    │   │   └── id.waydro.Mount.conf
    │   └── system-services
    │       └── id.waydro.Mount.service

If you encounter issues with waydroid not starting after installing microg or gapps, try the following solutions:

1. Ensure vanilla image usage: Confirm that you are using a vanilla image instead of a gapps version
2. Complete data reset: If the above methods still don't resolve the issue, completely remove the ~/.local/share/waydroid/data directory and re-run sudo waydroid init -f. Note: This operation will delete all waydroid data, so please ensure you have backed up any important information.

In some cases, ZygiskNext or ReZygisk may fail to function inside Waydroid.

These modules rely on SuperCall, a kernel-side IOCTL interface installed through a reboot kprobe hook. Waydroid's default seccomp profile blocks the reboot syscall, which prevents the SuperCall interface from being initialized.

Remove the reboot rule from the Waydroid seccomp configuration and then apply the change:

sudo sed -i '/reboot/d' /usr/lib/waydroid/data/configs/waydroid.seccomp
sudo waydroid upgrade -o

Special thanks to the scrcpy project. This project utilizes scrcpy's server component to enable seamless control of Android devices within Waydroid. The robust communication protocol and device interaction capabilities provided by scrcpy form the foundation of our key mapping features.