SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillswaydroid

waydroid

General & other

View repository

Updated 10-15 20:13

About this skill

Waydroid

Container-based Android for Linux with native Wayland integration.

Overview

Waydroid runs Android in a Linux container with near-native performance using namespaces (user, pid, uts, net, mount, ipc).

Key features:

  • Wayland Integration: Full support for Wayland compositors
  • GPU Acceleration: Hardware-accelerated graphics
  • Native Performance: Near-native speed vs emulators
  • LineageOS-based: Custom Android system images
  • binderfs: Android IPC mechanism for container-host communication

When Not to Use Waydroid

Use Case Better Alternative Trade-off
Need full Google Play Services fidelity AVD (Android Virtual Device) with Google APIs image AVD has higher overhead but complete Play Services compatibility
Testing hardware/GPU behavior Physical Android device Only real hardware reproduces device-specific GPU bugs
Running 5+ concurrent devices Cloud device lab (Firebase Test Lab, AWS Device Farm) Cost increases with scale, but built-in device diversity
Headless CI runners without display Genymotion Cloud or Android CI containers These provide headless Android runtime without display requirements
Building apps only (no runtime) Android SDK command-line tools + Gradle No emulator overhead when you only need to compile

CLI Quick Reference

Command Purpose
waydroid session start Start user session (after systemd container)
waydroid session stop Stop user session, keep container running
sudo systemctl start waydroid-container.service Start the Waydroid container (systemd)
sudo systemctl stop waydroid-container.service Stop the container completely
adb connect 192.168.250.1:5555 Connect ADB over Waydroid's network socket
waydroid app install <apk> Install an APK from host filesystem
waydroid app launch <package> Launch an installed Android app
waydroid screenshot Capture current screen to host
waydroid pull /sdcard/file Pull file from Android to host
sudo waydroid session stop && sudo rm -rf /var/lib/waydroid && sudo waydroid init Pull/reset image to restore state

Note: ADB over socket requires the container to be running. For deeper troubleshooting, see references/desktop-troubleshooting.md.

First 10 Minutes: Troubleshooting Path

When something doesn't work, follow this symptom → check order:

Symptom Check Depth
App won't install Verify image ABI: waydroid shell getprop ro.product.cpu.abi — x86_64 vs arm64-v8a mismatch requires different image references/gpu-networking.md
No network in Android ip addr show waydroid0 — interface should exist; waydroid shell ping google.com — tests DNS references/gpu-networking.md
Audio not working waydroid shell media list-sinks — verify audio sinks; try waydroid prop set audio.oss 1 references/desktop-troubleshooting.md
No hardware acceleration waydroid shell dumpsys SurfaceFlinger — check GPU renderer; verify virgl support references/gpu-networking.md
Container won't start `lsmod grep binder— binder module loaded?;waydroid log` — check init errors

Most common fix: sudo systemctl restart waydroid-container.service && waydroid session stop && waydroid session start

Installation

Ubuntu/Debian

sudo apt install curl ca-certificates python3-gbinder python3-trio -y
curl https://repo.waydro.id | sudo bash
sudo apt install waydroid -y

Supported: focal, jammy, kinetic, lunar, mantic, noble (Ubuntu); bullseye, bookworm, trixie, sid (Debian).

Fedora

sudo dnf copr enable aleasto/waydroid
sudo dnf install waydroid

For Silverblue/Kinoite: rpm-ostree install waydroid

Arch Linux

yay -S waydroid
# Or from git:
git clone https://aur.archlinux.org/waydroid.git && cd waydroid && makepkg -si

openSUSE

sudo zypper addrepo https://download.opensuse.org/repositories/openSUSE:Tools/openSUSE_Tools.repo
sudo zypper install waydroid

Void Linux

sudo xbps-install -S waydroid

Initialization

Basic

sudo waydroid init

With GApps

sudo waydroid init -s GAPPS

Manual OTA URLs

sudo waydroid init \
  -s https://ota.waydro.id/system \
  -v https://ota.waydro.id/vendor

Starting Waydroid

Using systemd (recommended)

sudo systemctl start waydroid-container.service
sudo systemctl enable waydroid-container.service
waydroid session start

Manual (without systemd)

sudo waydroid container start
waydroid session start

Common Commands

App Management

waydroid app install /path/to/app.apk
waydroid app list
waydroid app launch com.package.name
waydroid app uninstall com.package.name

Shell Access

waydroid shell
waydroid shell pm list packages
waydroid shell getprop ro.product.model
waydroid shell su -c "ls -la /sdcard/"

UI Control

waydroid show-full-ui
waydroid screenshot
waydroid window set <fullscreen|windowed|tablet> [position]

Status and Info

waydroid status
waydroid log
waydroid log -cat main
waydroid log -cat all
waydroid prop get
waydroid prop get ro.product.model

Container Control

waydroid session stop
sudo waydroid container stop
sudo waydroid container restart

Deep Dives

These reference files contain detailed information loaded on demand:

Best Practices

  1. Use Wayland session: Required for Waydroid
  2. Keep system updated: Ensures compatibility
  3. Use GAPPS if needed: Required for many apps
  4. Check logs first: waydroid log for troubleshooting
  5. Use proper GPU drivers: Install appropriate drivers
  6. Enable ADB for complex tasks: More control
  7. Back up data: Located in /var/lib/waydroid/

References