Use when setting up or troubleshooting Waydroid on Linux - installation and initialization, waydroid CLI, GPU and networking setup, GApps and Play certification, ADB integration, file sharing, or desktop environment integration
The English summary is being prepared. Showing the original description.
See how to installReview the instructions the agent will receive before you install.
Container-based Android for Linux with native Wayland integration.
Waydroid runs Android in a Linux container with near-native performance using namespaces (user, pid, uts, net, mount, ipc).
Key features:
| 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 |
| 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.
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
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).
sudo dnf copr enable aleasto/waydroid
sudo dnf install waydroid
For Silverblue/Kinoite: rpm-ostree install waydroid
yay -S waydroid
# Or from git:
git clone https://aur.archlinux.org/waydroid.git && cd waydroid && makepkg -si
sudo zypper addrepo https://download.opensuse.org/repositories/openSUSE:Tools/openSUSE_Tools.repo
sudo zypper install waydroid
sudo xbps-install -S waydroid
sudo waydroid init
sudo waydroid init -s GAPPS
sudo waydroid init \
-s https://ota.waydro.id/system \
-v https://ota.waydro.id/vendor
sudo systemctl start waydroid-container.service
sudo systemctl enable waydroid-container.service
waydroid session start
sudo waydroid container start
waydroid session start
waydroid app install /path/to/app.apk
waydroid app list
waydroid app launch com.package.name
waydroid app uninstall com.package.name
waydroid shell
waydroid shell pm list packages
waydroid shell getprop ro.product.model
waydroid shell su -c "ls -la /sdcard/"
waydroid show-full-ui
waydroid screenshot
waydroid window set <fullscreen|windowed|tablet> [position]
waydroid status
waydroid log
waydroid log -cat main
waydroid log -cat all
waydroid prop get
waydroid prop get ro.product.model
waydroid session stop
sudo waydroid container stop
sudo waydroid container restart
These reference files contain detailed information loaded on demand:
waydroid log for troubleshooting/var/lib/waydroid/No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
Use when building Python async HTTP services or clients with aiohttp - web server routing, middleware, WebSocket, SSE, streaming, client sessions, pytest-aiohttp testing, or troubleshooting SSL and timeout issues
The English summary is being prepared. Showing the original description.
Use when doing structural code search and rewriting - ast-grep linting, refactoring, multi-language patterns
The English summary is being prepared. Showing the original description.
Use when building GBA games with the BPCore Lua engine - entity, sprite and tilemap functions, SRAM save and load, link cable multiplayer protocol, camera and scrolling, or optimization patterns
The English summary is being prepared. Showing the original description.
Use when running background tasks with Celery - worker and broker configuration (Redis, RabbitMQ), task routing by name vs queue, chains/groups/chords, retry patterns (autoretry_for, retry_backoff), acks_late semantics, failure detection, and monitoring with Flower
The English summary is being prepared. Showing the original description.
Use when building Django applications - security hardening, authentication and permissions, ORM optimization, PostgreSQL features, Django 6.0, migrations, testing, and ecosystem libraries
The English summary is being prepared. Showing the original description.
Use when customizing Django Admin - save_formset, get_search_results, formsets, queryset optimization, db_index, custom URLs
The English summary is being prepared. Showing the original description.