WAYDROID(1)

NAME
waydroid - container-based approach to boot a full Android system on GNU/Linux

SYNOPSIS
waydroid [options] action [subaction] [args]

DESCRIPTION
waydroid is a system that runs a full Android system inside a container and integrates it with a Wayland compositor, allowing Android applications to run on a Gnu/Linux desktop. It supports multi‑window mode, full‑screen UI, and various configuration properties.

CONCEPTS
Waydroid is built upon three fundamental concepts. Understanding them helps with manual startup and troubleshooting.

Image
    An image is a pre‑built, read‑only filesystem of Android (including system and vendor partitions). Images are stored on disk, typically in /var/lib/waydroid/images. Waydroid downloads official images during waydroid init, or you can provide custom images using the -i option. Think of an image as an Android installation ISO that is not yet running.

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 must be started (usually with sudo waydroid container start) before any graphical output appears. You can stop, restart, freeze, or unfreeze the container. Container management requires root privileges.

Session
    The session is the component that bridges the Android container to the Wayland compositor. It handles graphics output (displaying Android UI), input events (mouse, keyboard, touch), and multi‑window integration. The session runs as a normal user (without root) with waydroid session start. After the session is started, Android apps become visible and interactive. Stopping the session (with waydroid session stop) only removes the graphical connection; the container may continue to run.

In normal usage with systemd services, these components are managed automatically. However, manual control is useful for debugging, custom setups, or when running without systemd.

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.

-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.

  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.

    Properties control the behaviour of Waydroid and the Android system. Use waydroid prop set property value to set a property. To unset, set the value to an empty string (""). Most properties require restarting the Waydroid session to 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.

•   After changing most properties, restart the Waydroid session: waydroid session stop and then waydroid session start.

•   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)

Project website: https://waydro.id
Documentation: https://docs.waydro.id
GitHub: https://github.com/waydroid/waydroid
Arch Wiki: https://wiki.archlinux.org/title/Waydroid

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