Setting Up Waydroid on Pop!_OS: The Definitive Guide to High-Performance Android Emulation (with Network & Customization Fixes)

tutorial.md

Setting Up Waydroid on Pop!_OS: The Definitive Guide to High-Performance Android Emulation (with Network & Customization Fixes)

For developers or mobile gamers looking for near-native Android emulation on Pop!_OS, traditional virtual machines often fall short due to massive emulation overhead. Waydroid offers a superior alternative. Unlike heavy emulation software, Waydroid uses Linux containers (LXC) to run a full Android system directly on the host kernel. The result is near-native, blazing-fast performance.

However, setting it up on Pop!_OS involves a few notorious hurdles—especially regarding kernel modules, network routing, and ARM translation for mobile gaming.

Here is the ultimate, battle-tested blueprint to get Waydroid up, running, connected, and customized on a Pop!_OS machine.

---

Prerequisites: The Wayland Check

Waydroid strictly requires a Wayland session. Verify the active display server by running:

echo $XDG_SESSION_TYPE

• If the output is wayland, the system is ready to roll.
• If the output is x11, log out, click the gear icon on the login screen, and switch to a Wayland session before proceeding.

---

Step 1: Solving the "Missing Kernel Modules" Error

Pop!_OS does not include the Android Binder IPC driver (binder_linux) natively in its standard kernel. Initializing Waydroid right away will result in a Failed to load binder driver error.

The cleanest fix is to switch to the XanMod Kernel, which includes the exact modules Waydroid needs out-of-the-box and offers excellent optimization for gaming. Run these commands:

wget -qO - https://dl.xanmod.org/archive.key | sudo gpg --dearmor -o /usr/share/keyrings/xanmod-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/xanmod-archive-keyring.gpg] http://deb.xanmod.org releases main' | sudo tee /etc/apt/sources.list.d/xanmod-release.list
sudo apt update && sudo apt install linux-xanmod-x64v3 -y

Reboot the computer to load into the new XanMod kernel before moving to the next step.

---

Step 2: Install and Initialize Waydroid

Now that the kernel has proper Binder support, add the official repository and pull down the Android image with Google Play Services (GApps):

sudo apt install curl ca-certificates -y
curl -s https://repo.waydro.id | sudo bash
sudo apt install waydroid -y

# Initialize with Google Apps
sudo waydroid init -s GAPPS -f
sudo systemctl enable --now waydroid-container

---

Step 3: Fixing the Post-Reboot "No Internet" Bug Permanently

Linux containers on Pop!_OS often struggle with DNS resolution and packet forwarding, wiping out the network configuration whenever the system reboots.

To bypass the Pop!_OS local network manager routing entirely and permanently lock in the internet connection, execute this sequence:

# 1. Hardcode Google DNS directly into the Android container properties
sudo waydroid prop set net.dns1 8.8.8.8
sudo waydroid prop set net.dns2 8.8.4.4

# 2. Persist IP Forwarding across system reboots
echo "net.ipv4.ip_forward = 1" | sudo tee /etc/sysctl.d/99-waydroid.conf
sudo sysctl -p /etc/sysctl.d/99-waydroid.conf

# 3. Configure UFW (Uncomplicated Firewall) exceptions for the bridge network
sudo ufw route allow in on waydroid0
sudo ufw route allow out on waydroid0
sudo ufw allow 53
sudo ufw allow 67
sudo ufw reload

# 4. Restart the container service
sudo systemctl restart waydroid-container

---

Step 4: Inject ARM Translation (libhoudini) & Certify Play Store

Most modern mobile games are built for ARM processors, but standard PC hardware runs an x86 architecture. Without a translation layer, games like Ragnarok Online Origin will instantly crash.

First, launch Waydroid once from the application menu (or run waydroid show-full-ui in a separate terminal) to generate the Android system folders, then close it.

Next, clone the community setup script to inject the libhoudini translation layer and register the device with Google:

sudo apt install git python3-venv -y
git clone https://github.com/casualsnek/waydroid_script
cd waydroid_script
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run the interactive script
sudo venv/bin/python3 main.py

In the script menu:

1. Go to Install -> Select libhoudini.
2. Return to the main menu -> Select Get Android Device ID.
3. Copy the long numerical ID provided.
4. Open a web browser, navigate to the Google Device Registration page, and paste the ID to whitelist the emulator. (Note: Activation typically takes Google 15–30 minutes).

---

Step 5: Power-User Customizations

Waydroid does not behave like a standard windowed app by default. Use these tweaks to make it feel like an integrated part of the desktop environment.

1. Window Resizing & Landscape Mode

To force a specific screen size (e.g., standard 16:9 landscape mode for gaming), set the preferred dimensions:

waydroid prop set persist.waydroid.width 1280
waydroid prop set persist.waydroid.height 720

# Stop the session to apply changes
waydroid session stop

If the user interface elements or fonts look too tiny or blown out at a custom resolution, dynamically tweak the pixel density:

waydroid shell wm density 240

(Standard target values are 160, 240, or 320. Use reset instead of a number to go back to default).

2. Enable Universal Host-to-Container Copy & Paste

To seamlessly sync the system clipboard back and forth between Pop!_OS and Android, install the required clipboard utilities:

sudo apt install wl-clipboard xclip python3-pip -y
sudo pip3 install pyclip --break-system-packages
waydroid session stop

---

Launching Your System

The configuration is now complete. To kickstart the environment from the command line moving forward, simply run:

waydroid show-full-ui

Log into the certified Google Play Store, download mobile titles, and enjoy massive frame rates running straight on bare-metal Linux hardware.

waydroid-manager.sh

#!/bin/bash

# ==============================================================================
# Waydroid Manager TUI for Pop!_OS (v4)
# Handles dependencies, installation, status checks, network, and cleanup.
# ==============================================================================

if [ "$EUID" -ne 0 ]; then
  echo "Please run this script with sudo: sudo ./waydroid-manager.sh"
  exit 1
fi

# ==========================================
# 1. Dependency & Status Checkers
# ==========================================
check_dependencies() {
    deps=(whiptail curl git python3-venv ufw iptables)
    missing_deps=()

    for dep in "${deps[@]}"; do
        if ! command -v "$dep" &> /dev/null; then
            missing_deps+=("$dep")
        fi
    done

    if [ ${#missing_deps[@]} -ne 0 ]; then
        echo "Installing missing dependencies: ${missing_deps[*]}..."
        apt-get update -y
        apt-get install -y "${missing_deps[@]}"
        echo "Dependencies installed successfully."
        sleep 1
    else
        echo "[ OK ] All required dependencies are already installed."
        sleep 2
    fi
}

get_system_status() {
    if command -v waydroid &> /dev/null; then
        if systemctl is-active --quiet waydroid-container; then
            echo "Waydroid: INSTALLED and RUNNING"
        else
            echo "Waydroid: INSTALLED (Service Stopped)"
        fi
    else
        echo "Waydroid: NOT INSTALLED"
    fi
}

# ==========================================
# 2. Core Functions
# ==========================================
install_waydroid() {
    if command -v waydroid &> /dev/null; then
        if ! whiptail --title "Already Installed" --yesno "Waydroid is already detected on this system. Proceed with reinstall?" 8 60; then
            return
        fi
    fi

    whiptail --title "Installing Waydroid" --msgbox "Adding repository and installing base packages. This may take a minute." 8 60
    
    apt-get install curl ca-certificates -y
    curl -s https://repo.waydro.id | bash
    apt-get install waydroid -y
    
    whiptail --title "Initializing Android" --msgbox "Downloading Google Play Apps (GAPPS). This takes a while depending on the internet speed." 8 60
    waydroid init -s GAPPS -f
    systemctl enable --now waydroid-container
    
    whiptail --title "Success" --msgbox "Waydroid base installation complete! Please run it once from the app menu before running the ARM Translator script." 8 60
}

fix_network() {
    if ! command -v waydroid &> /dev/null; then
        whiptail --title "Error" --msgbox "Waydroid must be installed before fixing the network." 8 60
        return
    fi

    whiptail --title "Fixing Network" --msgbox "Applying Pop!_OS specific DNS and routing bypasses..." 8 60
    
    waydroid prop set net.dns1 8.8.8.8
    waydroid prop set net.dns2 8.8.4.4
    
    echo "net.ipv4.ip_forward = 1" > /etc/sysctl.d/99-waydroid.conf
    sysctl -p /etc/sysctl.d/99-waydroid.conf
    
    ufw route allow in on waydroid0
    ufw route allow out on waydroid0
    ufw allow 53
    ufw allow 67
    ufw reload
    
    systemctl restart waydroid-container
    whiptail --title "Network Fixed" --msgbox "Firewall and routing rules applied permanently." 8 60
}

setup_arm_translator() {
    if ! command -v waydroid &> /dev/null; then
        whiptail --title "Error" --msgbox "Waydroid must be installed before adding the ARM translator." 8 60
        return
    fi

    whiptail --title "ARM Translator" --msgbox "Downloading the Waydroid Script tool to install libhoudini..." 8 60
    
    USER_HOME=$(eval echo ~${SUDO_USER})
    cd "$USER_HOME" || exit
    
    if [ ! -d "waydroid_script" ]; then
        git clone https://github.com/casualsnek/waydroid_script
    fi
    
    cd waydroid_script || exit
    python3 -m venv venv
    source venv/bin/activate
    pip install -r requirements.txt
    
    whiptail --title "Action Required" --msgbox "The script UI will now open. Select 'Install' -> 'libhoudini'. Then get the Device ID to certify with Google." 10 60
    
    python3 main.py
}

cleanup_waydroid() {
    if ! command -v waydroid &> /dev/null; then
        whiptail --title "Not Installed" --msgbox "Waydroid is not currently installed." 8 60
        return
    fi

    # Added explicit backup reminder and data loss warning text
    WARNING_TEXT="WARNING: Proceeding will completely remove Waydroid and permanently delete ALL Android data, including app progress, game files, configurations, and downloaded content.\n\nThis action cannot be undone. Ensure crucial files are backed up securely before continuing.\n\nDo you want to proceed with the deletion?"

    if whiptail --title "⚠️ CRITICAL WARNING: DATA LOSS" --yesno "$WARNING_TEXT" 14 65; then
        whiptail --title "Cleaning Up" --msgbox "Stopping services and purging data..." 8 60
        
        systemctl stop waydroid-container
        apt-get remove --purge waydroid -y
        
        rm -rf /var/lib/waydroid
        rm -rf /usr/share/waydroid
        rm -rf /etc/waydroid-runner
        
        USER_HOME=$(eval echo ~${SUDO_USER})
        rm -rf "$USER_HOME/.local/share/waydroid"
        rm -rf "$USER_HOME/.local/share/applications/*waydroid*"
        
        whiptail --title "Cleanup Complete" --msgbox "Waydroid has been completely wiped from the system." 8 60
    fi
}

# ==========================================
# 3. Main Menu Loop
# ==========================================
clear
check_dependencies

while true; do
    CURRENT_STATUS=$(get_system_status)
    
    CHOICE=$(whiptail --title "Waydroid Manager TUI" --menu "System Status: $CURRENT_STATUS\n\nSelect an operation:" 16 65 5 \
    "1" "Install Waydroid (GAPPS)" \
    "2" "Fix Pop!_OS Network Routing" \
    "3" "Setup ARM Translator (libhoudini)" \
    "4" "Nuclear Cleanup / Uninstall" \
    "5" "Exit" 3>&1 1>&2 2>&3)

    exitstatus=$?
    if [ $exitstatus != 0 ]; then
        clear
        exit 0
    fi

    case $CHOICE in
        1) install_waydroid ;;
        2) fix_network ;;
        3) setup_arm_translator ;;
        4) cleanup_waydroid ;;
        5) clear; exit 0 ;;
    esac
done

Easy way to install:
sudo bash -c "$(curl -sL https://gist.githubusercontent.com/jericbas/add9179bdee68f0cf6704f13ff8b6048/raw/fc9680d2d76e38145d847d95d2382f2302fee683/waydroid-manager.sh)"