Android on WSL2

Run a full Android environment on Windows Subsystem for Linux 2 using Waydroid. This toolkit handles everything from kernel compilation to Android setup, giving you a native Android experience inside WSL2.

📋 Overview

This project enables you to run Android apps and the full Android UI on WSL2 by:

Building a custom WSL2 kernel with Android Binder support
Installing Waydroid (Android 11 container) with Google Play Store
Configuring networking for Android app connectivity
Enabling audio support for media playback
Providing tools for file management between Windows and Android

🎯 What You Get

Full Android Experience

Android 11 running natively in WSL2
Google Play Store pre-installed (GAPPS)
Full UI with window manager support
App Installation via Play Store or APK files
Network Access for apps requiring internet
Audio Playback for media and games

Complete Automation

One-Click Kernel Build: Automated PowerShell + Bash scripts
Waydroid Setup: Single command installation with GAPPS
Web File Manager: Modern UI for Android file access
Auto-Configuration: BinderFS mounts automatically on boot

📦 Project Files

File	Purpose	When to Use
`Build-WSL_kernel.ps1`	Windows orchestrator	Run once to build kernel
`kernel-binder-build.sh`	Kernel compilation	Automatically called by PowerShell
`install-waydroid-gapps.sh`	Android setup	Run once after kernel is ready
`adb_file_manager.py`	File management UI	Optional, for easy file transfers

Verbose Mode

All main scripts support verbose output:

# Kernel build with full output
bash /tmp/kernel-binder-build.sh verbose

# Waydroid install with download progress
bash /tmp/install-waydroid-gapps.sh verbose

When to use verbose mode:

Debugging build/install issues
Monitoring download progress
Understanding what's happening
Reporting errors

When to use normal mode:

Clean, minimal output
Faster visual feedback
Production deployments

🚀 Quick Start Guide

Prerequisites

Windows 10/11 with WSL2 enabled
Ubuntu distribution installed in WSL
At least 10GB free disk space
30-40 minutes for initial setup

Step 0: Clone this Repo

git clone https://github.com/silentone12725/Android-on-WSL2.git

Step 1: Build Android-Ready Kernel

On Windows (Right-click → Run as Administrator):

.\Build-WSL_kernel.ps1

In Ubuntu/WSL (when prompted by PowerShell):

# Standard build (recommended)
bash /tmp/kernel-binder-build.sh

# Verbose mode (show all compiler output)
bash /tmp/kernel-binder-build.sh verbose

⏱️ Build time: 20-30 minutes

The script will:

Install build dependencies
Clone WSL2 kernel source from Microsoft
Configure Android Binder + networking + audio
Compile kernel and modules
Create VHDX module package
Copy everything to Windows

Step 2: Restart WSL with New Kernel

The PowerShell script will automatically:

Update your .wslconfig
Shutdown WSL
Prompt you to restart WSL

# Verify the new kernel is loaded
uname -r
# Should show: 6.6.114.1-microsoft-standard-WSL2+ (or similar)

# Check Android Binder support
ls -la /dev/binder*
# Should show: binder, hwbinder, vndbinder devices

Step 3: Install Android (Waydroid)

# Standard installation
bash /tmp/install-waydroid-gapps.sh

# Verbose mode (see all download/installation details)
bash /tmp/install-waydroid-gapps.sh verbose

⏱️ Installation time: 5-10 minutes (downloads ~500MB-1GB)

This installs:

Waydroid container system
Android 11 system image
Google Play Store (GAPPS)
All necessary Android services

Step 4: Launch Android!

# Start Android in full-screen mode
waydroid show-full-ui

🎉 You now have Android running on Windows via WSL2!

🌐 Managing Android Files

Web-Based File Manager

The included ADB file manager provides an easy way to transfer files between Windows/Linux and Android.

The script will automatically send the adb_file_manager.py file to the $HOME Directory on Ubuntu.

Run

waydroid show-full-ui

install adb and connect to waydroid (in a separate Ubuntu window)

Install ADB

sudo apt update 
sudo apt upgrade
sudo apt install adb

Connect ADB to Waydroid

waydroid adb connect

Start the server:

python3 adb_file_manager.py

Open in browser: http://localhost:8765

Features

Dual-pane UI: Windows/Linux (left) ↔ Android (right)
Drag & drop: Multi-file selection and transfer
APK installer: Direct install from host
Windows drives: Browse C:, D:, etc. on Windows
Virtual scrolling: Handle thousands of files smoothly

Usage Examples

Transfer photos from Android to Windows:

Left pane: Navigate to C:\Users\YourName\Pictures
Right pane: Navigate to /sdcard/DCIM/Camera
Select photos in right pane
Click PULL TO HOST

Install an APK:

Left pane: Navigate to your APK location
Select the APK file
Click INSTALL

Push files to Android:

Left pane: Select files/folders
Right pane: Navigate to destination (e.g., /sdcard/Download)
Click PUSH TO DEVICE

🔧 Additional Functionality

Enhance Your Android Experience

After basic setup, you can add powerful features using the waydroid_script toolkit:

Quick Install:

# Install dependencies and clone
sudo apt-get install -y python3 python3-pip lzip sqlite3
git clone https://github.com/casualsnek/waydroid_script.git
cd waydroid_script
pip3 install -r requirements.txt

Essential Enhancements

1. ARM Translation (Must-Have!)

Most Android apps are ARM-only. Enable them on x86:

# Install libhoudini for ARM app support
sudo python3 main.py install libhoudini

# Restart Waydroid
sudo waydroid session stop
sudo waydroid session start

# Verify (should show ARM architectures)
waydroid shell getprop ro.product.cpu.abilist

2. Google Play Certification

Fix "Device not certified" errors:

# Get your device ID
sudo python3 main.py certified

# Register at: https://www.google.com/android/uncertified/
# Wait 10-20 minutes, then clear Play Store cache:
waydroid shell pm clear com.android.vending
waydroid shell pm clear com.google.android.gms

3. Widevine DRM

Enable Netflix, Disney+, and other streaming services:

# Install Widevine L3
sudo python3 main.py install widevine

# Restart and clear streaming app data
sudo waydroid session stop
sudo waydroid session start

4. Root Access (Advanced)

For power users who need system-level access:

# Install Magisk
sudo python3 main.py install magisk

# Restart and configure in Android UI
sudo waydroid session stop
sudo waydroid session start
waydroid show-full-ui

Warning: Banking apps may refuse to run with root enabled.

Automated Setup Script

Complete enhancement in one command:

#!/bin/bash
# Save as: enhance-waydroid.sh

sudo waydroid session start
cd waydroid_script

# ARM translation + DRM + Certification
sudo python3 main.py install libhoudini
sudo python3 main.py install widevine
sudo python3 main.py certified

# Restart
sudo waydroid session stop
sudo waydroid session start

echo "Setup complete! Register device at:"
echo "https://www.google.com/android/uncertified/"

Run with: bash enhance-waydroid.sh

Feature Comparison

Feature	Best For	Command
libhoudini	ARM app compatibility	`sudo python3 main.py install libhoudini`
Widevine	Netflix, streaming apps	`sudo python3 main.py install widevine`
Certification	Play Store access	`sudo python3 main.py certified`
Magisk	Root access, mods	`sudo python3 main.py install magisk`
microG	Privacy-focused	`sudo python3 main.py install microg`

🎮 Using Android on WSL2

First Launch Setup

When you first launch Android:

Initial Boot: Takes 30-60 seconds
Setup Wizard: Follow Android's setup screens
Google Account: Sign in to access Play Store
Play Store: Browse and install apps normally

Essential Commands

# Launch Android UI
waydroid show-full-ui

# Start Android in background
waydroid session start

# Check Android status
waydroid status

# Stop Android
waydroid session stop

# Install APK file
waydroid app install /path/to/app.apk

# Launch specific app
waydroid app launch com.android.settings

# List installed apps
waydroid app list

# Open Android shell
waydroid shell

Installing Apps

Method 1: Google Play Store (Recommended)

Launch Android UI
Open Play Store app
Search and install apps normally

Method 2: APK Files

# From Linux/WSL
waydroid app install myapp.apk

# Using the web file manager (see below)
# 1. Open http://localhost:8765
# 2. Select APK in left pane
# 3. Click "INSTALL" button

Performance Tips

# For better performance, use system RAM for Waydroid
sudo mkdir -p /var/lib/waydroid
sudo mount -t tmpfs -o size=2G tmpfs /var/lib/waydroid

# Check Android system properties
waydroid shell getprop

# Monitor Android logs
waydroid logcat

🔧 Troubleshooting

Android Won't Start

Problem: waydroid show-full-ui fails or hangs

Solutions:

# Check if binder devices exist
ls -la /dev/binder*
# Should show: binder, hwbinder, vndbinder

# Verify kernel version
uname -r
# Should contain "WSL2" or your custom version

# Check Waydroid status
waydroid status

# Restart Waydroid session
waydroid session stop
sudo waydroid session start
waydroid show-full-ui

# Check logs
waydroid log

Binder Devices Missing

Problem: /dev/binder* symlinks not found after kernel update

Solution:

# Check if binderfs is mounted
mount | grep binder

# Manual mount (temporary fix)
sudo mkdir -p /dev/binderfs
sudo mount -t binder binder /dev/binderfs
sudo ln -sf /dev/binderfs/binder /dev/binder
sudo ln -sf /dev/binderfs/hwbinder /dev/hwbinder
sudo ln -sf /dev/binderfs/vndbinder /dev/vndbinder

# Enable automatic mounting
sudo systemctl enable binderfs.service
sudo systemctl start binderfs.service

Android Has No Internet

Problem: Apps can't connect to internet

Solution:

# Check network configuration
waydroid shell ip addr

# Restart networking
sudo waydroid-net.sh stop
sudo waydroid-net.sh start

# Verify iptables modules
lsmod | grep -E 'ip_tables|xt_'

# Manual module loading if needed
sudo modprobe xt_CHECKSUM
sudo modprobe iptable_mangle
sudo modprobe iptable_nat

Kernel Build Fails

Problem: Compilation errors during kernel build

Solutions:

# Clean and retry
cd ~/wsl-kernel-src/wsl-kernel
make clean
bash /tmp/kernel-binder-build.sh verbose

# Update build tools
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install -y build-essential bc flex bison

# Check disk space
df -h
# Need at least 10GB free

Play Store Not Working

Problem: Google Play Store won't open or sign in

Solution:

# Restart Android services
waydroid session stop
sleep 3
sudo waydroid session start
waydroid show-full-ui

# Re-initialize Waydroid (nuclear option)
sudo waydroid session stop
sudo rm -rf /var/lib/waydroid
bash /tmp/install-waydroid-gapps.sh

WSL Won't Start After Kernel Update

Problem: WSL fails to boot with custom kernel

Solution:

# On Windows PowerShell (as Admin)

# Check .wslconfig
cat $env:USERPROFILE\.wslconfig

# Verify kernel file exists
Test-Path "C:\Users\$env:USERNAME\wsl-kernel\bzImage-*"

# Temporarily revert to default kernel
# Comment out kernel line in .wslconfig
# (Edit: C:\Users\YourName\.wslconfig)
# Then:
wsl --shutdown
wsl -d Ubuntu

# Check WSL logs
wsl --debug-shell

Audio Not Working

Problem: No sound in Android apps

Check audio modules:

# Verify audio support in kernel
zcat /proc/config.gz | grep -E 'CONFIG_SND'

# Check loaded modules
lsmod | grep snd

# Try loading USB audio
sudo modprobe snd-usb-audio

Note: Audio in WSL2 is experimental. For best results, use WSLg (Windows 11) or a third-party X server.

Development & Testing

# Install your APK for testing
waydroid app install ~/myapp.apk

# View logs in real-time
waydroid logcat

# Access Android shell for debugging
waydroid shell

# Use ADB for advanced debugging
adb devices
adb logcat
adb shell dumpsys

Note: DRM-protected content may have limitations.

🛠️ Technical Details (For Advanced Users)

What Makes This Work

Android Binder IPC: Android's core inter-process communication system. Required for all Android apps to function.

BinderFS: Virtual filesystem that creates binder device nodes automatically.

Waydroid: Lightweight Android container that uses Linux namespaces and binder to run Android natively (not emulation).

Kernel Modules Enabled

The custom kernel includes these critical Android components:

CONFIG_ANDROID=y
CONFIG_ANDROID_BINDER_IPC=y
CONFIG_ANDROID_BINDERFS=y
CONFIG_ANDROID_BINDER_DEVICES="binder,hwbinder,vndbinder"

Networking for Android apps:

CONFIG_IP_NF_IPTABLES=y
CONFIG_IP_NF_MANGLE=y          # Required by Waydroid
CONFIG_IP_NF_NAT=y
CONFIG_NETFILTER_XT_TARGET_CHECKSUM=y  # Fixes network errors
CONFIG_BRIDGE=y
CONFIG_VETH=y
CONFIG_TUN=y

Audio support:

CONFIG_SND=y
CONFIG_SND_USB_AUDIO=y
CONFIG_SND_HDA_INTEL=y
CONFIG_SND_VIRTIO=y

Architecture

┌─────────────────────────────────────┐
│         Windows 10/11               │
│  ┌──────────────────────────────┐   │
│  │          WSL2                │   │
│  │  ┌────────────────────────┐  │   │
│  │  │  Custom Linux Kernel   │  │   │
│  │  │  (Android Binder)      │  │   │
│  │  └────────────────────────┘  │   │
│  │  ┌────────────────────────┐  │   │
│  │  │      Waydroid          │  │   │
│  │  │  (Android Container)   │  │   │
│  │  │  ┌──────────────────┐  │  │   │
│  │  │  │  Android 11      │  │  │   │
│  │  │  │  + GAPPS         │  │  │   │
│  │  │  └──────────────────┘  │  │   │
│  │  └────────────────────────┘  │   │
│  └──────────────────────────────┘   │
└─────────────────────────────────────┘

File Locations

Windows:

C:\Users\<YourName>\.wslconfig                    # WSL configuration
C:\Users\<YourName>\wsl-kernel\
  ├── bzImage-6.6.114.1-microsoft-standard-WSL2+  # Kernel image
  └── modules-6.6.114.1-microsoft-standard-WSL2+.vhdx  # Modules

Linux/WSL:

/var/lib/waydroid/                    # Android system files
~/.local/share/waydroid/              # Android user data
/dev/binderfs/                        # Binder devices
/tmp/                                 # Build scripts (temporary)

Performance Specs

Component	Resource Usage
Custom Kernel	+50-100MB RAM
Waydroid (Idle)	~200-300MB RAM
Waydroid (Active)	~500MB-1GB RAM
Android System	~500MB disk
App Storage	Variable

Build Process Details

When you run the build scripts:

PowerShell Script (Build-WSL_kernel.ps1):
- Copies bash script into WSL
- Monitors build progress
- Configures .wslconfig
- Manages WSL shutdown/restart
Bash Script (kernel-binder-build.sh):
- Installs: gcc, make, flex, bison, libelf, openssl
- Clones: Microsoft WSL2 kernel source (~1.5GB)
- Configures: Binder + networking + audio modules
- Compiles: Kernel in ~20-30 minutes
- Packages: Modules into VHDX format
- Exports: Files to Windows directory
Module VHDX Creation:
- Creates ext4 filesystem image
- Copies all kernel modules
- Converts to VHDX format (WSL2 native)
- Windows mounts this automatically on boot

❓ Frequently Asked Questions

Can I use this for app development?

Yes! This is perfect for testing Android apps. You get full ADB access and can use Android Studio's debugger.

Does this work on Windows 10?

Yes, as long as you have WSL2 enabled. Windows 11 recommended for better graphics support.

Will this break my existing WSL setup?

No. The custom kernel is isolated. You can revert by editing .wslconfig and running wsl --shutdown.

Can I run multiple Android instances?

Currently, Waydroid runs one instance per WSL distribution. You could use multiple WSL distros for multiple instances.

Does this require Hyper-V?

WSL2 uses Hyper-V automatically on Windows 10. On Windows 11, it uses the Virtual Machine Platform.

Can I play games?

Yes, but performance depends on the game. 2D games and light 3D games work well. Heavy games may lag.

Is this safe?

Yes. The kernel is built from official Microsoft sources with only configuration changes (no patches). Waydroid is open-source.

How do I update Android apps?

Through the Play Store, just like a regular Android device.

Can I use a different Android version?

Waydroid currently supports Android 11. Check their documentation for future versions.

How do I uninstall everything?

# Stop and remove Waydroid
sudo waydroid session stop
sudo apt-get remove --purge waydroid
sudo rm -rf /var/lib/waydroid ~/.local/share/waydroid

# Revert kernel (Windows PowerShell)
Remove-Item $env:USERPROFILE\.wslconfig
wsl --shutdown

# Optional: Remove build files
rm -rf ~/wsl-kernel-src ~/wsl-kernel-build

Then delete C:\Users\YourName\wsl-kernel\ from Windows.

🎓 Learning Resources

Understanding the Stack

WSL2 Documentation: Microsoft Learn
Waydroid Official: waydro.id
Android Binder: Android Source
Linux Kernel: kernel.org

Community & Support

Waydroid Issues: Report at Waydroid GitHub
WSL Issues: Report at WSL GitHub
This Project: Use GitHub Issues for toolkit-specific problems

🤝 Contributing

Contributions welcome! Areas of interest:

Kernel Improvements:

Additional Android features
Performance optimizations
Better audio support
GPU passthrough

Waydroid Enhancements:

Automated Play certification
Camera support
Better network configuration
Multi-window mode

Tools:

Enhanced file manager features
Backup/restore scripts
Performance monitoring
Auto-update mechanisms

Documentation:

Video tutorials
Troubleshooting guides
App compatibility lists
Benchmark results

How to Contribute

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

📊 Compatibility

Tested Configurations

Component	Version	Status
Windows 10 21H2	Build 19044	✅ Working
Windows 11 22H2	Build 22621	✅ Working
Ubuntu 20.04	WSL2	✅ Working
Ubuntu 22.04	WSL2	✅ Working
Waydroid	1.4.2+	✅ Working
Android	11	✅ Full support

📄 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

Microsoft for WSL2 and kernel source
Waydroid team for Android containerization
LineageOS for design inspiration
Community testers and contributors

🔐 Security & Privacy

What This Project Does

Builds kernel from official Microsoft sources
Applies only configuration changes (no code patches)
Runs Android in an isolated container
Requires explicit ADB authorization for file access

What You Should Know

Google Account: Required for Play Store access
App Permissions: Android apps run with normal permissions
Network Access: Apps can access internet through WSL2's network
Data Storage: Android data stored in /var/lib/waydroid/
File Isolation: Android can't access Windows files without explicit transfer

Privacy Notes

This setup does NOT bypass Google's SafetyNet
Banking apps may detect "rooted" environment
Some DRM content may be restricted
Android device ID is unique per Waydroid installation

Built with ❤️ for WSL2 + Android enthusiasts

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.gitattributes		.gitattributes
Build-WSL_kernel.ps1		Build-WSL_kernel.ps1
LICENSE		LICENSE
README.md		README.md
adb_file_manager.py		adb_file_manager.py
install-waydroid-gapps.sh		install-waydroid-gapps.sh
kernel-binder-build.sh		kernel-binder-build.sh

Folders and files

Latest commit

History

Repository files navigation

Android on WSL2

📋 Overview

🎯 What You Get

Full Android Experience

Complete Automation

📦 Project Files

Verbose Mode

🚀 Quick Start Guide

Prerequisites

Step 0: Clone this Repo

Step 1: Build Android-Ready Kernel

Step 2: Restart WSL with New Kernel

Step 3: Install Android (Waydroid)

Step 4: Launch Android!

🌐 Managing Android Files

Web-Based File Manager

Features

Usage Examples

🔧 Additional Functionality

Enhance Your Android Experience

Essential Enhancements

1. ARM Translation (Must-Have!)

2. Google Play Certification

3. Widevine DRM

4. Root Access (Advanced)

Automated Setup Script

Feature Comparison

🎮 Using Android on WSL2

First Launch Setup

Essential Commands

Installing Apps

Performance Tips

🔧 Troubleshooting

Android Won't Start

Binder Devices Missing

Android Has No Internet

Kernel Build Fails

Play Store Not Working

WSL Won't Start After Kernel Update

Audio Not Working

Development & Testing

🛠️ Technical Details (For Advanced Users)

What Makes This Work

Kernel Modules Enabled

Architecture

File Locations

Performance Specs

Build Process Details

❓ Frequently Asked Questions

Can I use this for app development?

Does this work on Windows 10?

Will this break my existing WSL setup?

Can I run multiple Android instances?

Does this require Hyper-V?

Can I play games?

Is this safe?

How do I update Android apps?

Can I use a different Android version?

How do I uninstall everything?

🎓 Learning Resources

Understanding the Stack

Community & Support

🤝 Contributing

How to Contribute

📊 Compatibility

Tested Configurations

📄 License

🙏 Acknowledgments

🔐 Security & Privacy

What This Project Does

What You Should Know

Privacy Notes

About

Resources

Stars

Watchers