Android debugging in VS Code and Windows Subsystem for Linux (WSL)

If you found this helpful or have feedback, feel free to share your thoughts with me via Twitter or LinkedIn.

The Windows Subsystem for Linux (WSL) has been a game-changer for software development on Windows. Paired with VS Code and its remote development feature, it is a powerful alternative to the traditional MacOS and Linux development environments. Having all my projects in VS Code within WSL has been a great development experience.

Recently, working with BookSloth on their Android app, I wanted to run and debug the app locally. One option was using Android Studio, but that meant giving up the uniformity of my development process. So I started setting up the project and the Android SDK in the WSL only. The problem came when running the emulator. WSL does not support virtualization out-of-the-box, and adding virtualization required experimental configurations. The solution was to run the emulator on the Windows host and bridging it to the WSL setup.

With this configuration, you’ll be able to do all your development inside the WSL with VS Code and debug your application on an emulator running on the Windows host.

Requirements

Setup is required for both the Windows host and the WSL in order to make this work. This was set up using the Ubuntu 20.04 for the WSL machine and probably works for other Linux distros. Commands for Windows are being run in PowerShell and bash in the WSL.

Feel free to customize names or directory locations in the following steps where necessarily to meet your requirements or accommodate them to your existing development environment.

SDK Setup

  • WSL and Windows — Create a directory called android wherever you specify your SDK files
  • WSL and Windows — Download the latest Command Line Tools from the link above and extract the .zip
  • WSL and Windows — Move cmdline-tools into the android directory
  • WSL and Windows — Move contents of cmdline-tools into a sub-folder called latest (assuming you’re using the latest version of the command line tools)
  • WSL and Windows — Configure the PATH location of the sdkmanager and other SDK tools:

Windows PATH

path\to\cmdline-tools\latest\bin
path\to\platform-tools
path\to\emulator

WSL Bash:

  • WSL — Install the build and platform tools for the target version. Check the app/build.gradle project file for the targetSdkVersion
sdkmanager "build-tools;<TARGET_VERSION>" "platforms;android-<TARGET_VERSION>" "platform-tools"
  • Windows — Install the platform and emulator tools and packages for the target version
sdkmanager "platforms;android-<TARGET_VERSION>" "platform-tools" "emulator"
  • WSL and Windows — Accept SDK licenses
sdkmanager — licenses

Emulator Setup

  • Windows — Download an Android Virtual Device (AVD) image
sdkmanager "system-images;android-<TARGET_VESION>;default;x86_64"
avdmanager create avd -name [AVDName] -package "[PACKAGE]" -device "[DEVICENAME]"
  • Windows — Add Firewall Rules to allow port traffic to and from WSL. Click here and here for more information on how to do so.
Preview of Windows Firewall Rules
  • WSL — Install the Android VS Code extension by adelphes
  • WSL — Change the host IP address in the adbSocket property in the .vscode/launch.json to the WSL host IP. This can be obtained using cat /etc/resolv.conf | grep nameserver | cut -d' '-f2
"adbSocket": "[WSL_HOST_IP]:5037"

Debugging

  • WSL — Build your project
  • Windows — Start the Android emulator
emulator -avd [AVDName]
  • Windows — Open port 5037 communication from Windows host to WSL
adb -a -P 5037 nodaemon server
  • WSL — Start debugging in VS Code by running the debug configuration created by the Android extension. Happy debugging!

Common Errors

Emulator — Dev computer keyboard not working in emulator

  • Go to path\to\.android\avd\AVDName.avd
  • In the config.ini file, change hw.keyboard to yes

Debug — Launch failed: ADBSocket Socket connect failed.

  • Check your debug launcher and emulator device are using the same port (defaulted to 5037)

Debug — Launch failed: No devices are connected

  • Check emulator is running
  • Check adb server is running in WSL
  • Check you installed the SAME version of adb on both Windows and WSL using adb - - version
  • Check you are using the adb command installed in the WSL. To avoid PATH mix-ups in WSL, disable importing your Windows PATH into WSL by creating the file /etc/wsl.conf/ and adding the lines
[interop]
enabled=false
appendWindowsPath=false
  • Check adb -a -P 5037 nodaemon server is running in Windows host
  • Check in Windows host Firewall is not blocking traffic from adb or WSL
  • Check the launch configuration has the correct WSL host IP and port in the adbSocket property

Co-founder and CTO of Hecdemi / Hyperion. Computer Engineer and entrepreneur from Puerto Rico 🇵🇷 Interested in combining tech, business, and product design.