Can I run the Android emulator inside WSL2?

Technically possible but not recommended. WSL2 has no nested virtualization by default and no GPU passthrough for the emulator. Run the emulator on Windows and connect to it from WSL2 by pointing the WSL adb client at the Windows adb server.

How do I use adb from WSL2 with a phone plugged into Windows?

Either forward the USB device into WSL2 with usbipd-win, or keep adb on Windows and set ADB_SERVER_SOCKET in WSL2 to the Windows host IP on port 5037. The second option is simpler and also works for the emulator.

Where should my Capacitor project live, in WSL2 or on the Windows drive?

Inside the WSL2 file system, for example /home/you/dev. Projects under /mnt/c are several times slower for node_modules and Gradle, and file watchers for live reload often miss changes there.

Can I build iOS from WSL2?

Not locally, since Xcode needs macOS. WSL2 runs the Capacitor CLI and cap sync ios fine, then Capgo Build compiles and signs the ios/ project in the cloud and can submit to TestFlight.

Capacitor-Entwicklung mit WSL2 unter Windows

WSL2 bietet Windows-Entwicklern eine echte Linux-Shell – entscheidend, wenn Skripte, Dockerfiles und CI deines Teams auf Bash setzen. Für Capacitor funktioniert das hervorragend, sofern man eine Regel beachtet: Die Web-Toolchain bleibt in WSL2, während Android-Emulator, USB-Geräte und Android Studio auf Windows laufen. Verbinde beides einfach via adb.

Dieser Guide zeigt das Setup, die Networking-Details, an denen viele scheitern, und wie iOS über Capgo Build.

Wann sich WSL2 lohnt

Nutze WSL2, wenn:

Dein Repo Bash-Skripte, Makefiles oder Husky-Hooks nutzt, die in PowerShell fehlschlagen.
Du dieselben Docker-Images lokal und in der CI ausführst.
Du das Linux- node_modules layout so lockfiles match your Linux CI.

Überspringe WSL2, wenn du nur Android Studio und ein Terminal brauchst. Der native Windows-Guide ist in diesem Fall einfacher.

1) WSL2 und eine Distribution installieren

In einer PowerShell mit Admin-Rechten:

wsl --install -d Ubuntu

Reboot, Ubuntu öffnen, Linux-User erstellen. Update und Basics installieren:

sudo apt update && sudo apt install -y build-essential unzip openjdk-21-jdk
curl -fsSL https://bun.sh/install | bash

2) Das Projekt im Linux-Dateisystem belassen

Erstelle Projekte in deinem Linux-Home, nicht unter /mnt/c:

mkdir -p ~/dev && cd ~/dev
bun create vite@latest my-app
cd my-app
bun install

Dateien über Windows-Tools über \\wsl$\Ubuntu\home\you\dev\my-app. VS Code mit der WSL-Extension öffnet sie direkt mit code ..

Warum das wichtig ist: Cross-Filesystem-Zugriffe über /mnt/c sind langsam bei den tausenden kleinen Dateien in node_modules, und die von Vite genutzten inotify-Watcher feuern bei Dateien auf dem Windows-Laufwerk nicht zuverlässig.

3) Festlegen, wo das Android SDK liegt

Zwei machbare Setups:

Layout A (empfohlen): SDK auf Windows, Gradle in WSL2 mit Verweis auf eine Linux SDK Kopie. Installiere Android Studio auf Windows für den Emulator und GUI-Tools, und ein separates CLI SDK in WSL2 für Gradle:

mkdir -p ~/Android/Sdk/cmdline-tools && cd ~/Android/Sdk/cmdline-tools
# download commandlinetools-linux-*.zip from the Android developer site
unzip commandlinetools-linux-*.zip && mv cmdline-tools latest
echo 'export ANDROID_HOME=$HOME/Android/Sdk' >> ~/.bashrc
echo 'export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools' >> ~/.bashrc
source ~/.bashrc
sdkmanager "platform-tools" "platforms;android-36" "build-tools;36.0.0"
sdkmanager --licenses

Ja, das verbraucht ein paar hundert Megabyte mehr. Dafür läuft Gradle mit Linux-Geschwindigkeit und ohne... /mnt/c.

Layout B: Alles auf Windows, WSL2 nur für den Web-Build. Du führst bun run build in WSL2 aus und cap sync plus gradlew über PowerShell auf denselben Dateien über \\wsl$. Es funktioniert, ist aber langsamer und vermischt zwei Shells. Nutze das nur, wenn du in WSL2 nichts installieren kannst.

Der Rest dieses Guides setzt Layout A voraus.

4) adb zwischen WSL2 und Windows bridgen

Der Emulator und USB-Geräte sind an Windows angebunden. Der WSL2 Gradle-Build und cap run android müssen darauf zugreifen können. Lass den adb-Server auf Windows laufen und nutze WSL2 nur als Client.

Starte auf Windows den adb-Server so, dass er auf allen Interfaces lauscht. Nutze dafür das adb aus dem Windows SDK:

adb kill-server
adb -a -P 5037 nodaemon server

Lass das Fenster offen. Erlaube den Port 5037 in der Windows-Firewall für den WSL-Virtual-Adapter, falls du dazu aufgefordert wirst.

Verweise in WSL2 den adb-Client auf den Windows-Host:

export WSL_HOST=$(ip route show default | awk '{print $3}')
export ADB_SERVER_SOCKET=tcp:$WSL_HOST:5037
adb devices

Der Emulator oder dein Phone wird nun in WSL2 angezeigt. Die beiden adb-Binaries müssen die gleiche Major-Version haben, also aktualisiere platform-tools gleichzeitig auf beiden Seiten.

Mirrored Networking vereinfacht das Ganze

Aktiviere unter Windows 11 22H2 oder neuer Mirrored Networking, damit WSL2 den Windows-Network-Stack nutzt. Erstelle oder bearbeite %USERPROFILE%\.wslconfig:

[wsl2]
networkingMode=mirrored

Ausführen wsl --shutdown, öffne Ubuntu neu und nutze ADB_SERVER_SOCKET=tcp:127.0.0.1:5037. Die Host-IP ändert sich nicht mehr bei jedem Reboot, und auch Live Reload wird einfacher.

Alternative: USB-Gerät an WSL2 durchreichen

Wenn du adb für ein physisches Phone vollständig in WSL2 nutzen willst, verwende usbipd-win:

winget install usbipd
usbipd list
usbipd bind --busid 2-3
usbipd attach --wsl --busid 2-3

Füge dann die udev-Regel aus dem Linux-Anleitung innerhalb von WSL2. Das hilft dem Emulator nicht, da dieser eine Netzwerkverbindung benötigt.

5) App starten

Mit dem adb-Bridge funktioniert Capacitor wie unter Linux:

bun add @capacitor/core @capacitor/android @capacitor/ios
bun add -d @capacitor/cli
bunx cap init
bun run build
bunx cap add android
bunx cap add ios
bunx cap run android

cap open android benötigt Android Studio auf derselben Maschine. Öffne stattdessen den android/ Ordner in Windows Android Studio über \\wsl$\Ubuntu\home\you\dev\my-app\androidDas mitgelieferte Gradle von Studio baut dann unter Windows, während dein Terminal in WSL2 baut; beide nutzen dieselben Quelldateien.

6) Live Reload über die Grenze hinweg

Vite läuft in WSL2, die App auf einem Windows-Emulator oder einem Smartphone. Der Emulator muss den Dev-Server erreichen.

Starte Vite, gebunden an alle Interfaces:

bun run dev -- --host 0.0.0.0

Verweise in Capacitor darauf unter capacitor.config.ts:

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'dist',
  server: {
    url: 'http://10.0.2.2:5173',
    cleartext: true,
  },
};

10.0.2.2 ist der Alias des Emulators für den Host. Mit Mirrored Networking ist der WSL2-Port am Windows-Host sichtbar, sodass diese Adresse Vite erreicht. Ohne Mirrored Networking musst du den Port unter Windows zuerst weiterleiten:

netsh interface portproxy add v4tov4 listenport=5173 listenaddress=0.0.0.0 connectport=5173 connectaddress=$(wsl hostname -I)

Verwenden Sie bei einem USB-Smartphone Ihre Windows-LAN-IP anstelle der URL und geben Sie Port 5173 in der Windows-Firewall frei. Führen Sie aus bunx cap sync android nach der Konfigurationsänderung aus und entferne den server -Block vor dem Release-Build.

7) iOS über WSL2 mit Capgo Build

Xcode benötigt macOS, daher übernimmt WSL2 alles bis zum Native Build, und Capgo erledigt den Rest:

bun run build
bunx cap sync ios
bunx @capgo/cli@latest login
bunx @capgo/cli@latest build init --platform ios
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release

Das CLI lädt das vorbereitete ios/ Projekt hoch und streamt die Logs zurück in dein WSL2-Terminal. Signing-Material wird ohne Mac via OpenSSL oder iOS-Zertifikatsgenerator erstellt. Alle Details findest du in Eine iOS-App unter Linux bauen mit Capacitor und Capgo Build, was für WSL2 unverändert gilt.

8) Native Builds für tägliche Änderungen vermeiden

Sobald beide Apps in den Stores sind, Capgo Live Updates Web-Änderungen via WSL2 pushen, ohne Gradle oder Capgo Build zu nutzen:

bunx @capgo/cli@latest bundle upload --channel production

Häufige WSL2-Probleme

adb: device offline oder leere Liste in WSL2: der Windows adb-Server läuft nicht mit -a, oder die Versionen unterscheiden sich. Starte ihn neu und vergleiche adb version beide Seiten.
Host-IP nach Reboot geändert: bei fehlendem Mirrored Networking normal. Setze den WSL_HOST exportieren in ~/.bashrc , damit er neu berechnet wird, oder wechsle in den Mirrored Mode.
Vite erkennt Dateiänderungen nicht: Projekt liegt unter /mnt/c. Verschiebe es ins Linux-Home.
Gradle extrem langsam: gleiche Ursache, oder der Gradle-Cache liegt auf /mnt/c. Behalte ihn ~/.gradle in WSL2.
Clock Drift bricht Apple API Authentifizierung bei build init: WSL2-Uhren driften nach dem Standby ab. Führe sudo hwclock -s and retry.
cap open android schlägt fehl: Studio läuft auf Windows. Öffne den Ordner stattdessen direkt aus Studio.

Zusammenfassung

WSL2 ist die ideale Umgebung für die Capacitor Web-Toolchain, wenn dein Team in bash arbeitet. Behalte den Emulator und die Geräte unter Windows, verbinde sie über einen adb-Server, speichere Dateien im Linux-Dateisystem und überlasse den iOS-Compile dem Capgo Build. Das Ergebnis ist ein Linux-Workflow auf einem Windows-Laptop, der trotzdem in beide App Stores liefert.