waydroid

Start Waydroid

$ waydroid

$ sudo waydroid init

$ waydroid app install [path/to/file.apk]

$ waydroid app launch [com.example.app]

$ waydroid session [start|stop]

$ sudo waydroid container [start|stop|restart|freeze|unfreeze]

$ sudo waydroid shell

$ waydroid prop set persist.waydroid.[width|height] [number]

waydroid <command> [<args>]

Common commands include:
waydroid init
waydroid start
waydroid stop
waydroid shell
waydroid show-full-ui
waydroid app install <path_to_apk>

init
    Initializes the Waydroid container, typically downloading Android system images. Often run as sudo waydroid init.

start
    Starts the Waydroid container. Requires the container to be initialized.

stop
    Stops the running Waydroid container.

restart
    Restarts the Waydroid container.

status
    Displays the current operational status of the Waydroid container.

log
    Shows logs generated by the Waydroid container, useful for debugging.

shell
    Connects to the Waydroid container's Android Debug Bridge (ADB) shell.

update
    Updates the Waydroid container's system images to the latest available version.

show-full-ui
    Displays the full Android user interface in a dedicated window on the host system.

app
    Subcommand for managing Android applications within the container, e.g., waydroid app install <path_to_apk>.

prop
    Subcommand for managing Android system properties within the container.

device
    Subcommand for managing Waydroid devices or sessions.

session
    Subcommand for managing Waydroid graphical sessions.

config
    Subcommand for managing Waydroid configuration settings.

container
    Subcommand for advanced management of the underlying LXC container.

version
    Displays the Waydroid client and container version information.

help
    Shows general help or specific help for a subcommand, e.g., waydroid help init.

Waydroid is an open-source project that provides a way to run a full Android operating system in a Linux container. It leverages LXC (Linux Containers) to isolate the Android environment from the host system, while using Wayland for display rendering, enabling seamless integration with the host's graphical environment. Unlike traditional emulators, Waydroid runs a real Android system, providing near-native performance for Android applications. It requires a Wayland compositor and specific kernel modules (like binder_linux and ashmem_linux) to function correctly.

Waydroid is often used for running Android apps that are not available natively on Linux, for development and testing of Android applications, or for general Android usage within a secure containerized environment on a desktop Linux system. Its design aims to be a successor to projects like Anbox, offering improved stability and performance.

Wayland Requirement: Waydroid fundamentally relies on a Wayland compositor for its graphical output and will not function correctly on Xorg sessions without complex workarounds.
Kernel Modules: Requires specific kernel modules like binder_linux and ashmem_linux to be loaded on the host system.
Root Privileges: Initial setup, starting, stopping, and updating the container often require root privileges (e.g., using sudo).
Performance Variability: Performance can vary significantly depending on host hardware specifications and the overall system configuration.
Integration Limitations: Direct integration with host system features (e.g., notifications, clipboard sharing, file system access) might be limited or require additional manual setup.

The very first step after installing Waydroid is usually to run sudo waydroid init. This command downloads the necessary Android system and vendor images, preparing the container for use. It's crucial to be running a Wayland session on your desktop environment (e.g., GNOME on Wayland, KDE Plasma on Wayland) for Waydroid's graphical output to function, as it does not natively support Xorg.

Waydroid emerged as a successor to projects like Anbox, aiming to provide a more stable and performant solution for running Android on Linux. It is based on Project Halium, which provides the necessary compatibility layer for Android to run on standard Linux kernels. Development has focused on leveraging modern Linux technologies like Wayland and LXC to improve integration and performance compared to its predecessors, becoming a popular choice for users seeking to run Android applications natively on their Linux desktops.

lxc(1), adb(1), systemctl(1), anbox(1)