Skip to content

Instantly share code, notes, and snippets.

@bergmannjg
Last active May 27, 2025 01:54
Show Gist options
  • Save bergmannjg/461958db03c6ae41a66d264ae6504ade to your computer and use it in GitHub Desktop.
Save bergmannjg/461958db03c6ae41a66d264ae6504ade to your computer and use it in GitHub Desktop.
Building a react native app in WSL2

Building a react native app in WSL2

Install, build and debug a react native app in WSL2 (Windows Subsystem for Linux) and Ubuntu.

Install tools in Windows

  • Install WSL2 and Ubuntu, see here
  • Install Android Studio, see here
  • Install Viusal Studio Code, see here

Enable mirrored networking mode in WSL2

Mirrored mode networking has the goal of 'mirroring' the network interfaces that you have on Windows into Linux. All programs on Windows and Linux can connect via localhost.

Add the following lines to %UserProfile%/.wslconfig (thanks to @craigjones-dev)

[wsl2]
networkingMode=mirrored
hostAddressLoopback=true

Install tools in WSL2

  • Install java-21-openjdk in WSL2 (sudo apt-get install openjdk-21-jre)
  • Install Android SDK cmdline tools in WSL2, see here and adjust directory structure, see here
  • Install nodejs in WSL2, see here

Set environment variables in .profile or .bash_profile

export ANDROID_HOME=/home/xxx/Android/cmdline-tools/latest
export ANDROID_SDK_ROOT=/home/xxx/Android

PATH=$PATH:$ANDROID_SDK_ROOT/platform-tools
PATH=$PATH:$ANDROID_HOME/bin

export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64

Connect to android hardware device from Windows

To debug on a hardware device connect to android device via adb

  • start adb server in Windows: adb kill-server && adb server start

Connect to android hardware device from WSL2

To debug on a hardware device connect to android device via usbip and adb from WSL2 (thanks to @cjshearer):

Connect to android virtual device in Windows

To debug on a virtual device

  • create a virtual device in windows with Android Virtual Device Manager, see here
  • start the Android Emulator, see here, the adb server automatically starts on Windows.

Create react native app in WSL2

npx react-native init AwesomeProject

Build app in WSL2

Start metro JavaScript bundler and bind to an ipv4 address to enable port forwarding to windows

npx react-native start --host 127.0.0.1

Build app, set device as parameter deviceId from result of adb devices

  • deviceId emulator: emulator-5554
npx react-native run-android --variant=debug --deviceId <deviceId>

Debug app in Visual Studio Code from WSL2

Start vs code in WSL2

code .

and install extensions for VS Code

  • Remote - WSL
  • React Native Tools

VS Code UI runs in windows and the VS Code Server runs in WSL2, see here

Add a launch configuration in file launch.json with specified type and request

"name": "Attach to packager",
"cwd": "${workspaceFolder}",
"type": "reactnative",
"request": "attach"

Build app, attach to packager and start debugging, see here.

@AnthonyTailer
Copy link

I always have to execute the Metro Bundler Forwarding to connect to react-native... anyone knows why? Is there a definitive way to do this?

@pelarejo
Copy link

I also have to execute the Metro Bundler Forwarding on startup before npm start.
I created a simple script executable from WSL to start the forwarding, along with starting the adb server.
I thought I'd share it here:

  • some/wsl/folder/start_adb.sh
#!/usr/bin/env sh

winpwd=$(printf "%s" "$PWD" | sed 's/\//\\/g')
powershell.exe Start-Process -Verb runas powershell.exe -ArgumentList "\"-NoExit -ExecutionPolicy Bypass \\\\wsl\$\\Ubuntu$winpwd\\proxy_adb.ps1\""
  • some/wsl/folder/proxy_adb.ps1
# Forward metro
iex "netsh interface portproxy delete v4tov4 listenport=8081 listenaddress=127.0.0.1" | out-null;
$WSL_CLIENT = bash.exe -c "ip addr show eth0 | grep -oP '(?<=inet\s)\d+(\.\d+){3}'";
$WSL_CLIENT -match '\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}';
$WSL_CLIENT = $matches[0];
iex "netsh interface portproxy add v4tov4 listenport=8081 listenaddress=127.0.0.1 connectport=8081 connectaddress=$WSL_CLIENT"
# Start adb server
adb kill-server
adb -a nodaemon server start

Simply launch the start_adb script, it will prompt you for admin rights. Remember to add adb to windows path.

@cjshearer
Copy link

cjshearer commented Nov 7, 2021

New Method for Android

  1. Install the sdk manager (without needing android studio).

  2. For physical devices: usbipd-win can now be used to expose your android device (or any usb device) directly in WSL2. I've tested and used this to deploy react-native apps to my android device. In addition, this method will work with debugging tools like Flipper, as it doesn't rely on a Windows ADB server.

See the discussion here if you have any issues getting it working for ADB: dorssel/usbipd-win#60

@bergmannjg
Copy link
Author

@cjshearer thank you very much, got it work on my box

@RakaDoank
Copy link

@cjshearer @bergmannjg i'm trying to connect my Android device from WSL2. Everything is fine with usbipd-win, even my device shows up in "adb devices" command (WSL2). But i get an error when i try "npx react-native run-android"

error Failed to install the app. Make sure you have the Android development environment set up: https://facebook.github.io/react-native/docs/getting-started.html#android-development-environment. Run CLI with --verbose flag for more details.Error: Command failed: ./gradlew app:installDebug -PreactNativeDevServerPort=8081

Also, i've tried with "npx react-native run-android --deviceId=", still i get an error, but it says

error Failed to build the app. Run CLI with --verbose flag for more details. Error: Command failed: ./gradlew build -x lint

How do you guys make it work?
My last last last step is use Ubuntu directly (dual boot alongside Windows).

@bergmannjg By the way, i've also tried connecting android virtual device in Windows from WSL2, and i also get the second error.

@bergmannjg
Copy link
Author

@RakaDoank what is the error msg of

./gradlew app:installDebug -PreactNativeDevServerPort=8081

@RakaDoank
Copy link

RakaDoank commented Dec 24, 2021

@bergmannjg i get

bash: ./gradlew: No such file or directory

i only found out the error after you asked. So, i tried gradle wrapper first and run the ./gradlew command again, then i get this new error

Project 'app' not found in root project 'myProject'

I'm sorry, this is probably not a WSL issue.

@iamdevlinph
Copy link

Has anyone have an updated version of the guide? Been stuck on different places.

@0xElectric
Copy link

ERROR ON:

adb kill-server
adb -a nodaemon server start

emulator-5554: already offline
what does this mean?
error

@luizwhite
Copy link

luizwhite commented Apr 30, 2022

For those struggling with Expo with the error Couldn't start project on Android: could not connect to TCP port 5554: Connection refused

I'm no expert, but debugging things a little with variables EXPO_DEBUG=1 and ADB_TRACE=adb, I found out that expo start was executing the command adb -s emulator-5554 emu avd name , and somehow this command from the Ubuntu side didn't work (maybe someone here can help fix this), but the adb running on Windows could run that command from Ubuntu with adb.exe.

So, I successfully overrode that with sudo ln -s /mnt/c/Android/Sdk/platform-tools/adb.exe ~/Android/sdk/platform-tools/adb after backing up the original ubuntu adb executable (just fix that path with your windows adb path and your possible custom ubuntu adb path)
image

I did that only when running the expo start command and all worked smoothly (until now at least)

If anyone can help us to find out why adb on ubuntu side cannot access the emulator, I would appreciate it (even when adb devices runs normally and lists the device)


PS: all worked without

  • any netsh interface portproxy or
  • any adb reverse or
  • firewall rule to allow WSL ports (only rule to allow adb program)
  • admin rights command execution
  • socat alternative

But I used the variables below:

export WSL_HOST=$(tail -1 /etc/resolv.conf | cut -d' ' -f2)
export ADB_SERVER_SOCKET=tcp:$WSL_HOST:5037
export ADB_TRACE=adb
export EXPO_DEBUG=1
export ANDROID_SERIAL=emulator-5554
export REACT_NATIVE_PACKAGER_HOSTNAME=$(ip addr show eth0 | grep -oP '(?<=inet\s)\d+(\.\d+){3}')

and...

  • used same version of platform-tools on both windows and ubuntu
  • used adb kill-server && adb -a -P 5037 nodaemon server start on Windows side after emulator loaded

versions...

  • Windows 11 and Ubuntu 20.04
  • expo-cli 5.4.3
  • last version of node and npm (v16.15.0 - v8.8.0)
  • emulator running avd Pixel_4_API_30 with Google APIs
  • usb debug mode enabled on emulator
  • adb version 1.0.41 and platform-tools 33.0.1

@craftogrammer
Copy link

For those struggling with Expo with the error Couldn't start project on Android: could not connect to TCP port 5554: Connection refused

I'm no expert, but debugging things a little with variables EXPO_DEBUG=1 and ADB_TRACE=adb, I found out that expo start was executing the command adb -s emulator-5554 emu avd name , and somehow this command from the Ubuntu side didn't work (maybe someone here can help fix this), but the adb running on Windows could run that command from Ubuntu with adb.exe.

So, I successfully overrode that with sudo ln -s /mnt/c/Android/Sdk/platform-tools/adb.exe ~/Android/sdk/platform-tools/adb after backing up the original ubuntu adb executable (just fix that path with your windows adb path and your possible custom ubuntu adb path) image

I did that only when running the expo start command and all worked smoothly (until now at least)

If anyone can help us to find out why adb on ubuntu side cannot access the emulator, I would appreciate it (even when adb devices runs normally and lists the device)

PS: all worked without

  • any netsh interface portproxy or
  • any adb reverse or
  • firewall rule to allow WSL ports (only rule to allow adb program)
  • admin rights command execution
  • socat alternative

But I used the variables below:

export WSL_HOST=$(tail -1 /etc/resolv.conf | cut -d' ' -f2)
export ADB_SERVER_SOCKET=tcp:$WSL_HOST:5037
export ADB_TRACE=adb
export EXPO_DEBUG=1
export ANDROID_SERIAL=emulator-5554
export REACT_NATIVE_PACKAGER_HOSTNAME=$(ip addr show eth0 | grep -oP '(?<=inet\s)\d+(\.\d+){3}')

and...

  • used same version of platform-tools on both windows and ubuntu
  • used adb kill-server && adb -a -P 5037 nodaemon server start on Windows side after emulator loaded

versions...

  • Windows 11 and Ubuntu 20.04
  • expo-cli 5.4.3
  • last version of node and npm (v16.15.0 - v8.8.0)
  • emulator running avd Pixel_4_API_30 with Google APIs
  • usb debug mode enabled on emulator
  • adb version 1.0.41 and platform-tools 33.0.1

Thanks, @luizwhite , it really helped. It was the easiest one I found on the internet so far 😊 . Let's wait for someone who got some ideas about it.

@bongofury
Copy link

@luizwhite thanks a lot! Your solution works like a charm. That's what I was searching for. 🍺

@amaxalov
Copy link

For the proxy to work properly with socat. still need to run npx react-native start --host 0.0.0.0 without 127.0.0.1

@iago-silva
Copy link

Wonderful!

@dkornilove
Copy link

dkornilove commented Jul 26, 2022

I had the experience of successfully setting up and running react native applications on WSL + Windows AVD emulator with using socat command. But recently I moved to a new computer and did everything as it was on the last machine, only with a newer SDK and tools versions and after running the adb devices command on the WSL, I get this error
adb: failed to check server version: protocol fault (couldn't read status): Success
while windows adb server and socat command run successfully.
And when I kill the socat process, adb devices command works well, but without seeing the windows emulator for sure.
All SDK and tool versions are the same on Windows and WSL.
Can someone help me figure out what it is?

socat log for the adb devices query

2022/07/26 17:28:34 socat[2129] N opening connection to AF=2 172.17.96.1:5037
2022/07/26 17:29:07 socat[2129] E connect(5, AF=2 172.17.96.1:5037, 16): Connection timed out
2022/07/26 17:29:07 socat[2129] N exit(1)

upd: solved by adding the firewall rule for adb.exe

@kicksent
Copy link

kicksent commented Aug 30, 2022

and adjust directory structure, see here

Wish this section was more clear.

@hec-lopz
Copy link

I had problems using expo and the solution @luizwhite gave worked for me.

So, I successfully overrode that with sudo ln -s /mnt/c/Android/Sdk/platform-tools/adb.exe ~/Android/sdk/platform-tools/adb after backing up the original ubuntu adb executable (just fix that path with your windows adb path and your possible custom ubuntu adb path)

However, I'm concerned there could be any kind of performance issues due to WSL2 accessing Windows memory. It would be great if anyone could point out if it could become an issue going forward.

@dexterbrylle
Copy link

@luizwhite I was able to connect the emulator. However when I run npx expo start --android I get this error. The Expo-*.apk exists in the directory. Any idea?
image

@dexterbrylle
Copy link

NVM, I was able to install the apk with: adb install Exponent-2.28.6.apk.

@eynopv
Copy link

eynopv commented May 24, 2023

Having issue with npx expo start
Getting error: could not connect to TCP port 5554: Connection refused.

Set environment variables

export WSL_HOST=$(tail -1 /etc/resolv.conf | cut -d' ' -f2)
export ADB_SERVER_SOCKET=tcp:$WSL_HOST:5037
export ANDROID_SERIAL=emulator-5554
export REACT_NATIVE_PACKAGER_HOSTNAME=$(ip addr show eth0 | grep -oP '(?<=inet\s)\d+(\.\d+){3}')

Starting adb in Windows, emulator was started before

> adb -a nodaemon -P 5037 server start
adb.exe I 05-24 10:56:45 20016 16472 auth.cpp:416] adb_auth_init...
adb.exe I 05-24 10:56:45 20016 16472 auth.cpp:152] loaded new key from 'C:\Users\***\.android\adbkey' with fingerprint A7A3F84B061B063E11EFD5034A7C67ED92AA52C7AA569BE5BEE9BD597E01DDB2
adb.exe I 05-24 10:56:45 20016  5140 transport.cpp:335] emulator-5554: read thread spawning
adb.exe I 05-24 10:56:45 20016 17240 transport.cpp:307] emulator-5554: write thread spawning
adb.exe I 05-24 10:56:45 20016 16472 adb.cpp:173] emulator-5554: already offline

adb in WSL

> adb devices
List of devices attached
emulator-5554   device
> adb shell
emu64xa:/ $

@Nifled
Copy link

Nifled commented Jul 11, 2023

It's ridiculous how complicated it is to set up a dev environment

@0xElectric
Copy link

I give up, it's better to learn a native language for mobile or something.

@osherz
Copy link

osherz commented Jul 13, 2023

I give up, it's better to learn a native language for mobile or something.

Or just don't use wsl2.
I give up wsl2...

@rzjnzk
Copy link

rzjnzk commented Jul 13, 2023

There is a typo in the file name. rearct-native-app-in-wsl2.md -> react-native-app-in-wsl2.md.

@0xElectric
Copy link

I give up, it's better to learn a native language for mobile or something.

Or just don't use wsl2. I give up wsl2...

yes, you're right

@cjshearer
Copy link

@sprngLf @osherz this is the same conclusion I came to. WSL is awesome...unless you need usb. I abandoned Windows on my work machine because react-native dev, while possible on WSL, is just too much maintenance on top of an already very complicated framework.

@vagnerlandio
Copy link

I didn't follow the guide and I didn't need to do any extra config to make the react native environment work in WSL and testing on a physical device or WSA (Windows Subsystem for Android).

Just on physical device I enabled wifi debugging and on WSL:

adb pair <ip:port of physical device connected on the same network of the host computer that is running the WSL>
adb connect <ip:port>

npx react-native start
npx react-native run-android

After the build process then the app started both on the physical device and also on the WSA

@AdalZayas
Copy link

@vagnerlandio Thanks for that solution, i was trying to not leave wsl because i so greate for me, and my workspace is all around windows, so trying to find a solution to not use a device connected to my pc it was hard. To all who wants to usea a emulator, just install the WSA (Windows Subsystem for Android) and having the command line tools from android installed on WSL, you just do:

adb connect <ip:port> (try with 127.0.0.1:58526 if isn't working use yout local ip ex: 10.5.0.2:58526)

The port you can find it on the WSA > Advance Settings > Developer mode

Then run:

adb devices

List of devices attached
6pt8t8dqzhtwswz5        device
10.5.0.2:58526      device

With that now you can just run your command to run your RN app on the WSA

@ben-rochlin
Copy link

this is more of a comment, but all this feels very un-intuitive and damn near impossible.

@jeroenwienk
Copy link

Why do we need to start the metro bundle with --host 127.0.0.1. I can access the bundle fine from windows with a browser without setting the host but its not possible with the emulator that runs in windows. I fail to understand why.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment