Waydroid Installation and Usage Guide on X11

Table of Contents

1. Introduction
2. System Requirements
3. Installation
   • Install Weston
   • Install Waydroid
   • Initialize Waydroid
4. Usage
   • Launching Waydroid
   • Stopping Waydroid
5. Additional Configuration
   • Hiding Waydroid Apps from the System Launcher
   • Enable Clipboard on Weston
6. Automation
   • Creating Automated Startup Scripts
7. Troubleshooting
8. References

---

Introduction

This guide provides comprehensive instructions for installing and using Waydroid on an X11-based Linux system. Waydroid is a powerful tool that enables you to run Android in a containerized environment on Linux, giving you a full Android system experience directly on your desktop.

---

System Requirements

Before you proceed, ensure that your system meets the following prerequisites:

• A working X11 environment.
• Administrative privileges (sudo access).
• curl and ca-certificates installed.

Ensure you have these dependencies installed by running:

sudo apt install curl ca-certificates -y

---

Installation

Install Weston

Weston is a reference Wayland compositor required by Waydroid to render the Android interface. Install Weston with the following command:

sudo apt install weston -y

Install Waydroid

Follow these steps to install Waydroid on your system.

Step 1: Add the Waydroid Repository

Run the following command to add the official Waydroid repository:

curl https://repo.waydro.id | sudo bash

Step 2: Install Waydroid

Once the repository is added, install Waydroid using:

sudo apt install waydroid -y

---

Initialize Waydroid

Waydroid initialization must be done from within the Weston session. Follow these steps to initialize Waydroid:

1. Start Weston:

   In a terminal, run:

   weston --socket=mysocket

   This command starts a Weston session on the specified socket.

2. Switch to the Weston terminal:

   In the Weston terminal window (where Weston is running), perform one of the following initialization commands depending on your preference.

Vanilla Android Initialization

To initialize Waydroid without Google Apps (GAPPS), run:

sudo waydroid init

Android with GAPPS

To initialize Waydroid with Google Apps (GAPPS) support, use:

sudo waydroid init -f -s GAPPS

After initialization, Waydroid is ready to be launched. You can now proceed with launching Waydroid using the instructions below.

Fix missing binder (if any)

if somehow u got this error :

[21:15:53] Failed to load binder driver
[21:15:53] modprobe: FATAL: Module binder_linux not found in directory /lib/modules/6.8.0-76060800daily20240311-generic
[21:15:53] ERROR: Binder node "binder" for waydroid not found
[21:15:53] See also: <https://github.com/waydroid>
Run 'waydroid log' for details.

u can follow this guide to solve the error.

---

Usage

Launching Waydroid

Once initialized, you can launch Waydroid within a Weston session using the following steps:

1. Start Weston:

   In a terminal, run:

   weston --socket=mysocket

   This command initializes a Weston session with a specific socket.

2. Launch Waydroid:

   Inside the Weston terminal, start the Waydroid user interface:

   waydroid show-full-ui

   This will boot the full Android system within the Wayland environment.

Stopping Waydroid

When you are finished using Waydroid, you can stop the session by running:

waydroid session stop

This will gracefully terminate the Waydroid session.

---

Additional Configuration

Hiding Waydroid Apps from the System Launcher

By default, Waydroid apps may appear in your system launcher. To prevent this and keep your launcher clean, run the following script:

for a in ~/.local/share/applications/waydroid.*.desktop; do
    grep -q NoDisplay $a || sed '/^Icon=/a NoDisplay=true' -i $a
done

This script adds the NoDisplay=true entry to each Waydroid .desktop file, effectively hiding them from the system launcher.

Enable Clipboard on Weston

To enable clipboard functionality between Weston and X11 environments, follow these steps:

1. Install pyclip (Python clipboard library):

   sudo pip install pyclip

2. Install wl-clipboard (Wayland clipboard utility):

   sudo apt install wl-clipboard

With these tools, you can now share clipboard data between your Waydroid session and the X11 environment, making copy-pasting more seamless.

---

Automation

You can automate Waydroid’s startup and shutdown processes by creating scripts and a desktop entry.

Creating Automated Startup Scripts

1. Create a Weston Configuration File

Create a ~/.config/weston.ini file to configure Weston’s behavior:

[libinput]
enable-tap=true

[shell]
panel-position=none

This configuration improves input handling and removes the panel from Weston.

2. Create a Waydroid Startup Script

Save the following script as /usr/bin/waydroid-session.sh:

#!/bin/bash

# Start Weston
weston --xwayland &
WESTON_PID=$!
export WAYLAND_DISPLAY=wayland-1
sleep 2

# Launch Waydroid
waydroid show-full-ui &
WAYDROID_PID=$!

# Function to stop Waydroid
stop_waydroid() {
    waydroid session stop
    kill $WESTON_PID
    kill $WAYDROID_PID 2>/dev/null
}

# Wait for Weston to finish
wait $WESTON_PID

# Stop Waydroid after Weston exits
stop_waydroid

Make the script executable:

chmod +x /usr/bin/waydroid-session.sh

3. Create a Desktop Entry

Create a desktop entry to easily launch the session from your system launcher. Save the following as /usr/share/applications/waydroid-session.desktop:

[Desktop Entry]
Version=1.0
Type=Application
Name=Waydroid Session
Comment=Launch Waydroid X11 Session
Exec=/bin/bash -c "cd /usr/bin && ./waydroid-session.sh"
Icon=waydroid
Terminal=false
Categories=System;Emulator;

Make the desktop entry executable:

chmod +x /usr/share/applications/waydroid-session.desktop

---

Troubleshooting

If you encounter any issues, consider the following:

• Weston fails to start: Ensure that you have Weston installed and your X11 session is running correctly.
• Waydroid session does not launch: Check your Weston configuration and ensure that Waydroid is properly installed.
• Performance issues: Consider allocating more system resources to Waydroid and Weston by adjusting your system settings.

For advanced troubleshooting, consult the official Waydroid documentation.

---

References

• Waydroid Official Documentation
• Weston Reference Documentation

---

This guide now includes the initialization steps for Waydroid, both with and without GAPPS, and instructions for enabling clipboard functionality inside the Weston.