Introduction to Waydroid and Its RootFS

Waydroid provides a seamless way to run a full Android system on a Linux device, leveraging LXC containers to integrate deeply with the host OS. At its core, Waydroid operates using a set of Android images, primarily system.img and vendor.img, which together form the Android Root File System (RootFS). While the stock Waydroid setup offers a functional experience, advanced users often seek to customize this environment—whether to integrate specific custom ROM features, install Google Play Services (GApps), or remove unwanted bloatware. This guide will delve into the intricacies of Waydroid’s RootFS, explaining how to extract, modify, and rebuild it to achieve a truly personalized Android experience within Waydroid.

Understanding Waydroid’s RootFS Structure

The Waydroid RootFS is comprised of several key images, typically located in /var/lib/waydroid/images/:

• system.img: This is the primary Android system partition, containing the Android OS framework, core applications, libraries, and resources.
• vendor.img: This image holds device-specific binaries and libraries provided by the device manufacturer. For Waydroid, this often contains Waydroid-specific adaptations.
• waydroid_rootfs.squashfs (or similar): This might sometimes be present as a base read-only root filesystem for the container itself, but for Android modifications, we primarily focus on system.img and vendor.img.

These images are often in a sparse format (.img) optimized for flashing. To modify them, we first need to convert them into a raw, mountable format.

Prerequisites: Tools and Setup

Before we begin, ensure you have the necessary tools installed on your Linux host system:

sudo apt update
sudo apt install android-sdk-platform-tools simg2img img2simg e2fsprogs

You will also need:

• A Waydroid installation (ensure it’s not running during modifications).
• A custom ROM image (e.g., LineageOS AOSP build) if you plan to replace the entire system. Waydroid usually provides its own `system.img`. For integrating GApps, you’ll modify the existing `system.img`.
• A GApps package (e.g., OpenGApps, NikGApps) compatible with your Android version and architecture (usually ARM64). Download the zip file.

It’s crucial to stop Waydroid before modifying its images to prevent data corruption:

sudo systemctl stop waydroid-container
sudo systemctl stop waydroid-session

Step-by-Step RootFS Modification

1. Backup Existing Images

Always start with a backup of your original Waydroid images:

sudo cp /var/lib/waydroid/images/system.img /var/lib/waydroid/images/system.img.bak
sudo cp /var/lib/waydroid/images/vendor.img /var/lib/waydroid/images/vendor.img.bak

2. Convert Sparse Image to Raw

Waydroid’s system.img is a sparse image. Convert it to a raw ext4 image that can be mounted:

cd /var/lib/waydroid/images/
sudo simg2img system.img system.raw.img

This creates system.raw.img, which is a full-size ext4 filesystem image.

3. Mount the Raw Image

Create a mount point and mount the raw image:

sudo mkdir /mnt/waydroid_rootfs
sudo mount -o loop system.raw.img /mnt/waydroid_rootfs

Now, the contents of your Waydroid’s system partition are accessible under /mnt/waydroid_rootfs.

4. Modifying the RootFS (e.g., Integrating GApps)

This is where the actual customization happens. For GApps integration, you’ll essentially copy the GApps package contents into the mounted system.raw.img directory structure. Remember, you’re directly manipulating the filesystem, not flashing a ZIP.

First, extract your GApps .zip file to a temporary location. For example, if you downloaded open_gapps-arm64-11.0-nano-*.zip:

unzip /path/to/open_gapps-arm64-11.0-nano-*.zip -d /tmp/gapps_extracted

The extracted GApps package typically contains a Core directory, which has app, priv-app, etc, framework, and other directories. You need to copy these over to your mounted Waydroid system:

sudo cp -r /tmp/gapps_extracted/Core/* /mnt/waydroid_rootfs/

Be mindful of permissions. Files copied directly might not have the correct SELinux contexts or ownership. While cp -r preserves some, it’s often safer to fix them later if issues arise. For initial GApps integration, directly copying is usually sufficient.

You might also want to:

• Remove bloatware: Navigate to /mnt/waydroid_rootfs/system/app or /mnt/waydroid_rootfs/system/priv-app and delete unwanted APK directories.
• Edit build.prop: Open /mnt/waydroid_rootfs/system/build.prop with a text editor (sudo nano /mnt/waydroid_rootfs/system/build.prop) to change system properties.
• Add custom scripts or binaries: Place them in appropriate locations like /mnt/waydroid_rootfs/system/bin or /mnt/waydroid_rootfs/system/xbin.

Important consideration for GApps: Some GApps packages include installer scripts that perform additional actions like adjusting permissions or creating symlinks. When manually copying, you might miss these. For Waydroid, a direct copy often works, but if you encounter issues, consider manually creating missing symlinks or adjusting permissions/SELinux contexts post-boot via adb shell if Waydroid still starts.

5. Unmount the Image

Once all modifications are complete, unmount the image:

sudo umount /mnt/waydroid_rootfs
sudo rmdir /mnt/waydroid_rootfs

6. Repair and Shrink the Filesystem (Optional but Recommended)

Running filesystem checks and shrinking the image can help reduce its size and ensure integrity:

sudo e2fsck -fy system.raw.img
sudo resize2fs -M system.raw.img

The -M flag for resize2fs will shrink the filesystem to its minimum possible size.

7. Convert Raw Image Back to Sparse

Convert the modified raw image back into a sparse image, suitable for Waydroid:

sudo img2simg system.raw.img system.new.img

This creates system.new.img, which is now your customized Waydroid system image.

8. Replace the Original Waydroid Image

Finally, replace Waydroid’s original system.img with your new, customized version:

sudo mv system.new.img system.img
sudo rm system.raw.img

Booting Waydroid and Verification

Now, restart the Waydroid container and session:

sudo systemctl start waydroid-container
sudo systemctl start waydroid-session

Launch Waydroid. You should now see the changes reflected. If you installed GApps, you might need to go through an initial setup process within Android to log into your Google account. Ensure you have network connectivity enabled for Waydroid.

If Waydroid fails to start or encounters a boot loop, revert to your backup (system.img.bak) and review your modification steps.

Advanced Considerations and Troubleshooting

• SELinux Contexts: Incorrect SELinux contexts are a common cause of boot failures or app crashes. While cp usually tries to preserve them, if you manually create files or directories, you might need to use chcon or enable
  
  Android Mobile Specs & Compare Directory

  Are you researching mobile hardware properties, processor SoCs, GPU chipsets, or RAM configurations? Access our complete specs catalog to compare up to 5 devices side-by-side!

  Compare Devices Specs →