WAYDROID(1)

📦 version 1.6.3, in ubuntu stonking

💖 WAYDROID 💖

okay bestie, so like — this is the waydroid manual page, from the User Commands section of the manual. It's giving "run a whole entire Android on your Linux desktop" energy and honestly? iconic. Let's get into it. 🫶

✨ NAME ✨

waydroid — a container-based approach to booting a full Android system on GNU/Linux. no cap, a whole phone, on your laptop. 🌸

✨ SYNOPSIS ✨

waydroid [options] action [subaction] [args]

✨ DESCRIPTION ✨

so waydroid is this whole system that runs a full Android system inside a container and integrates it with a Wayland compositor, which means Android apps can just… run on your Gnu/Linux desktop?? like they live there now. 💅

it supports:

  • multi-window mode
  • full-screen UI
  • and a whole pile of configuration properties

main character energy fr fr.

✨ CONCEPTS ✨

Waydroid is built on three fundamental concepts, and lowkey understanding them is the whole key to manual startup and troubleshooting. like, if you get these three, you get Waydroid. periodt.

  • Image — an image is a pre-built, read-only filesystem of Android (system and vendor partitions included). Images live on disk, typically in /var/lib/waydroid/images. Waydroid downloads official images during waydroid init, or you can bring your own custom images with the -i option. think of an image as an Android installation ISO that isn't running yet. it's just… sitting there. waiting. 💀
  • Container — the container is the running instance of an Android image. it uses Linux namespaces and cgroups to run the Android userspace in isolation, sharing the host kernel. the container has to be started (usually with sudo waydroid container start) before any graphical output shows up. you can stop it, restart it, freeze it, or unfreeze it. and heads up: container management requires root privileges. 👑
  • Session — the session is the component that bridges the Android container to the Wayland compositor. it handles graphics output (showing the Android UI), input events (mouse, keyboard, touch), and multi-window integration. the session runs as a normal user (no root!) with waydroid session start. once the session is up, Android apps become visible and interactive. stopping the session (with waydroid session stop) only removes the graphical connection — the container may keep running.

so in normal usage with systemd services, all of these components are managed automatically. but manual control is highkey useful for debugging, custom setups, or when you're running without systemd at all.

✨ OPTIONS ✨

  • -h, --help — show help message and exit. 🎀
  • -V, --version — show program's version number and exit.
  • -l LOG, --log LOG — path to log file (default: /var/lib/waydroid).
  • --details-to-stdout — print details (e.g. build output) to stdout instead of writing to the log.
  • -v, --verbose — write even more to the logfiles (may reduce performance 😭).
  • -q, --quiet — do not output any log messages. silent. mysterious.
  • -f — force options (used with init actions).
  • -i LOCATION — initialize from specified location (default: /usr/share/waydroid-extra/images). used only with the init action.

✨ ACTIONS ✨

  • status — quick check of the waydroid status. vibe check, basically.
  • log — follow the waydroid logfile.
  • init — set up waydroid specific configs and install images.
  • upgrade — upgrade images.
  • session — session controller (start/stop the Wayland integration).
  • container — container controller (start/stop/freeze/unfreeze the Android container).
  • app — applications controller (install, remove, launch, list apps).
  • prop — Android properties controller.
  • show-full-ui — show Android full screen in a window.
  • shell — run a remote shell command inside the container.
  • logcat — show Android's logcat.

✨ INIT OPTIONS ✨

used with waydroid init to control image sources and type.

  • -h, --help — show help for init and exit.
  • -i IMAGES_PATH, --images_path IMAGES_PATH — custom path to store downloaded images (default: /var/lib/waydroid/images).
  • -f, --force — force initialization, useful when resetting or using custom images.
  • -c SYSTEM_CHANNEL, --system_channel SYSTEM_CHANNEL — URL of the OTA channel for the system image (default: official Waydroid server).
  • -v VENDOR_CHANNEL, --vendor_channel VENDOR_CHANNEL — URL of the OTA channel for the vendor image (default: official server).
  • -r ROM_TYPE, --rom_type ROM_TYPE — ROM flavour: lineage (default, LineageOS-based), bliss (BlissOS-based), or a custom OTA URL.
  • -s SYSTEM_TYPE, --system_type SYSTEM_TYPE — type of system regarding Google services: VANILLA (no Google apps), FOSS (free/open alternatives), or GAPPS (Google Play Services). default is VANILLA.

✨ LOG OPTIONS ✨

used with waydroid log.

  • -h, --help — show help for log and exit.
  • -n LINES, --lines LINES — number of initial output lines to show.
  • -c, --clear — clear the log file.

✨ CONTAINER SUBACTIONS ✨

used with waydroid container.

  • -h, --help — show help for container and exit.
  • start — start the container (requires root/sudo). 👑
  • stop — stop the container.
  • restart — restart the container.
  • freeze — freeze the container. ❄️
  • unfreeze — unfreeze the container.

✨ SESSION SUBACTIONS ✨

used with waydroid session.

  • -h, --help — show help for session and exit.
  • start — start the Wayland session (run as normal user, not root).
  • stop — stop the Wayland session.

✨ APP SUBACTIONS ✨

used with waydroid app.

  • -h, --help — show help for app and exit.
  • install APK_FILE — push a single package to the container and install it.
  • remove PACKAGE_NAME — remove single app package from the container.
  • launch PACKAGE_NAME — start single application.
  • list — list all installed applications.

✨ PROPERTIES ✨

used with waydroid prop.

  • -h, --help — show help for prop and exit.
  • get PROPERTY — get value of property from container.
  • set PROPERTY VALUE — set value to property on container.

so properties control the behaviour of Waydroid and the Android system. use waydroid prop set property value to set a property. to unset one, set the value to an empty string (""). and ngl, most properties need you to restart the Waydroid session before they actually take effect. 🙈

🌈 Behaviour 🌈

  • persist.waydroid.multi_windows (true/false) — enable/disable window integration with the desktop (multi-window mode).
  • persist.waydroid.height_padding (0-9999) — adjust height padding.
  • persist.waydroid.width_padding (0-9999) — adjust width padding.
  • persist.waydroid.width (0-9999) — override desired resolution width.
  • persist.waydroid.height (0-9999) — override desired resolution height.
  • persist.waydroid.suspend (true/false) — let the container sleep after display timeout when no apps are active (default: true on kernel 4.9+).
  • persist.waydroid.uevent (true/false) — allow Android direct access to hotplugged devices (default: false).
  • persist.waydroid.reverse_scrolling (true/false) — invert the direction of scrolling (default: false).

🍓 App behaviour 🍓

  • persist.waydroid.fake_touch (string, max 91 chars) — comma-separated list of package names for which mouse inputs are interpreted as touch inputs. supports wildcard *.
  • persist.waydroid.fake_wifi (string, max 91 chars) — comma-separated list of package names for which the system always appears as if connected to Wi-Fi. supports wildcard *.

🔥 Debug 🔥

  • persist.waydroid.no_presentation (true/false) — disable the wp_presentation protocol.
  • persist.waydroid.invert_colors (true/false) — swap the color space from RGBA to BGRA.
  • persist.waydroid.cursor_on_subsurface (true/false) — draw the cursor on a subsurface instead of the cursor surface.
  • persist.waydroid.cursor_force_shm (true/false) — always submit wl_shm buffers for the cursor surface.
  • persist.waydroid.no_background_subsurface (true/false) — do not submit a black background subsurface.
  • persist.waydroid.use_subsurface (true/false) — submit overlayed subsurfaces rather than letting Android compose the stack.

✨ EXAMPLES ✨

📝 Logging 📝

waydroid log > ~/waydroid-log.txt

📝 Logcat 📝

sudo waydroid logcat > ~/waydroid-logcat.txt

📝 Initialization with custom images 📝

# Clean previous data (reboot if errors occur)
sudo rm -rf /var/lib/waydroid /home/.waydroid ~/waydroid
# Force init to use custom images from default extra directory
sudo waydroid init -f
# Or use a custom path
sudo waydroid init -f -i ~/Downloads/test_build

📝 Initialization with specific ROM and GAPPS 📝

sudo waydroid init -r lineage -s GAPPS

📝 Starting Waydroid manually 📝

# Terminal 1 (as root)
sudo waydroid container start
# Terminal 2 (as normal user)
waydroid session start
# After "Android with user 0 is ready", launch full UI
waydroid show-full-ui

📝 Multi-window mode 📝

waydroid prop set persist.waydroid.multi_windows true
waydroid session stop
# Now launching apps will open in separate windows

📝 App management 📝

waydroid app install ~/Downloads/example.apk
waydroid app launch com.example.app
waydroid app list
waydroid app remove com.example.app

✨ NOTES ✨

  • many operations require root privileges (use sudo). the session start command, however, must be run as a normal user under a Wayland compositor. don't mix these up bestie, it will Not work. 😭
  • after changing most properties, restart the Waydroid session: waydroid session stop and then waydroid session start. every single time. no shortcuts.
  • APK files that only contain ARM binaries will not work on x86_64 hosts. consider installing F-Droid or a Play Store image for graphical app management. 💀

✨ SEE ALSO ✨

adb(1)

✨ AUTHOR ✨

Waydroid is maintained by the Waydroid team. this manual page was written for the Debian project based on upstream documentation. 🫶

so yeah, that's the whole thing. waydroid, dated 2025-03-15, this page being the WAYDROID(1) manual page from the User Commands section. go run some Android on your desktop, you absolute legend. 💖✨👑

📦 where this page comes from