Set Up Your Environment

In this guide, you'll learn how to set up your environment, so that you can build and run React Native desktop apps on your own machine. A desktop app is a regular native executable for the operating system you develop on: you build macOS apps on a Mac, Windows apps on Windows, and Linux apps on Linux.

info

The first build of an app compiles the Rust renderer and takes a few minutes. Later builds are incremental. If the toolchain below is already installed, you should be up and running within a few minutes. Otherwise, expect about half an hour to install the compilers.

Development OS

macOS
Windows
Linux

Installing dependencies

You will need Node, Rust, CMake and Xcode.

Node and Rust are used on every operating system. React Native needs Node.js 22.13 or newer, and the desktop renderer is written in Rust, so you need a stable Rust toolchain installed with rustup.

Node and Rust

We recommend installing Node and CMake using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install node cmake

Install Rust with rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Restart your Terminal afterwards so that cargo is on your PATH.

note

If you already have Node installed, make sure it is Node 22.13 or newer. Check with node --version.

Xcode

Install Xcode from the Mac App Store. The command line tools alone are not enough: the renderer compiles Metal shaders, and the Metal shader compiler ships with Xcode.

After installing Xcode:

Open Xcode once and accept the license agreement, or run sudo xcodebuild -license accept.
Make sure the command line tools point to Xcode: open Xcode > Settings > Locations and pick your Xcode version in the Command Line Tools dropdown, or run sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer.
On Xcode 26 and newer, the Metal toolchain is a separate download:

xcodebuild -downloadComponent MetalToolchain

Verifying your setup

Open a new Terminal and run the doctor:

npx @react-native-gpui/cli doctor

It checks every tool on this page and prints how to fix each one that is missing or misconfigured:

Text
Desktop development on macOS
 ✓ Node.js 22.20.0
 ✓ Rust 1.96.0
 ✓ Cargo 1.96.0
 ✓ CMake 3.31.4
 ✓ Xcode 26.6
 ✓ Xcode license
 ✖ Metal shader compiler: the Metal toolchain is not installed
     Fix: xcodebuild -downloadComponent MetalToolchain

1 problem found.

Inside a React Native project, npx react-native doctor-desktop runs the same checks, and npx react-native doctor lists them in a Desktop section next to its own.

Troubleshooting

xcrun: error: unable to find utility "metal": the Metal toolchain is not installed. Run xcodebuild -downloadComponent MetalToolchain on Xcode 26 and newer, and check that the command line tools point to the full Xcode and not to /Library/Developer/CommandLineTools.
cargo: command not found: restart the Terminal, or run source "$HOME/.cargo/env".
Building for Intel and Apple silicon: the app is built for the architecture of the Mac you build on.

Installing dependencies

You will need Node, Rust, CMake, Perl, NASM and the Visual Studio C++ build tools.

React Native needs Node.js 22.13 or newer, and the desktop renderer is written in Rust, so you need a stable Rust toolchain installed with rustup.

Install the tools

We recommend installing the tools with winget, which ships with current versions of Windows. Run the following commands in a PowerShell window:

winget install -e --id Microsoft.VisualStudio.2022.BuildTools --override "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
winget install -e --id Kitware.CMake
winget install -e --id StrawberryPerl.StrawberryPerl
winget install -e --id NASM.NASM
winget install -e --id Rustlang.Rustup
winget install -e --id OpenJS.NodeJS.LTS

Tool	Used for
Visual Studio 2022 Build Tools	The MSVC compiler, linker and Windows SDK
CMake	Building React Native's C++ runtime and native modules
Strawberry Perl	Building native dependencies
NASM	Building native dependencies
Rustup	The Rust toolchain that builds the renderer
Node.js LTS	Metro and the React Native tooling (22.13 or newer)

Configure `PATH`

Two things need a manual step:

Add NASM to PATH. Its installer does not. Add C:\Program Files\NASM to your user PATH.
Keep Strawberry Perl ahead of Git's Perl. Git for Windows ships its own perl, which cannot build the native dependencies. In your PATH settings, move the Strawberry Perl entry (C:\Strawberry\perl\bin) above C:\Program Files\Git\usr\bin, if the latter is present.

Enable long paths

Native builds create deeply nested folders. Enable long paths once, from an administrator PowerShell:

New-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem -Name LongPathsEnabled -Value 1 -PropertyType DWORD -Force

Restart your machine afterwards. If Git is installed, also run git config --system core.longpaths true.

Use the Developer PowerShell

Run every build from a Developer PowerShell for VS 2022. Open it from the Start menu, or from a normal PowerShell with:

& "${env:ProgramFiles(x86)}\Microsoft Visual Studio\2022\BuildTools\Common7\Tools\Launch-VsDevShell.ps1" -Arch amd64

It sets up the compiler environment (cl.exe, link.exe and the Windows SDK paths) that the build expects.

Verifying your setup

Open a new Developer PowerShell and run the doctor:

npx @react-native-gpui/cli doctor

It checks every tool on this page and prints how to fix each one that is missing or misconfigured:

Text
Desktop development on Windows
 ✓ Node.js 22.20.0
 ✓ Rust 1.96.0
 ✓ Cargo 1.96.0
 ✓ CMake 3.31.4
 ✓ MSVC compiler
 ✖ Strawberry Perl: perl resolves to C:\Program Files\Git\usr\bin\perl.exe, not to Strawberry Perl
     Fix: Move C:\Strawberry\perl\bin above Git's usr\bin in PATH
 ✓ NASM 2.16.03
 ✓ Long paths

1 problem found.

Inside a React Native project, npx react-native doctor-desktop runs the same checks, and npx react-native doctor lists them in a Desktop section next to its own.

Troubleshooting

nasm is not recognized: C:\Program Files\NASM is not on PATH. Add it and open a new terminal.
cl is not recognized: you are not in a Developer PowerShell. Open Developer PowerShell for VS 2022.
Perl errors during the build: Git's Perl is found before Strawberry Perl. Reorder PATH as described above.
"Filename too long" errors: long paths are not enabled yet. Enable them and restart.

Installing dependencies

You will need Node, Rust, CMake, a C++ compiler and a few development packages.

React Native needs Node.js 22.13 or newer, and the desktop renderer is written in Rust, so you need a stable Rust toolchain installed with rustup.

System packages

Install the compiler, CMake, pkg-config, Perl and the X keyboard and XCB development libraries with your distribution's package manager:

Debian / Ubuntu
Fedora
Arch

sudo apt install build-essential cmake pkg-config perl \
  libxkbcommon-dev libxkbcommon-x11-dev libxcb1-dev

sudo dnf install gcc-c++ make cmake pkgconf perl \
  libxkbcommon-devel libxkbcommon-x11-devel libxcb-devel

sudo pacman -S base-devel cmake perl libxkbcommon libxkbcommon-x11 libxcb

Node and Rust

Install Node.js 22.13 or newer. Your distribution's package may be older, so we recommend nvm or the NodeSource packages:

nvm install 22

Install Rust with rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Restart your terminal afterwards so that cargo is on your PATH.

Verifying your setup

Open a new terminal and run the doctor:

npx @react-native-gpui/cli doctor

It checks every tool on this page and prints how to fix each one that is missing or misconfigured:

Text
Desktop development on Linux
 ✓ Node.js 22.20.0
 ✓ Rust 1.96.0
 ✓ Cargo 1.96.0
 ✓ CMake 3.28.3
 ✓ C++ compiler 13.2.0
 ✓ pkg-config 1.8.1
 ✓ Perl 5.38.2
 ✓ xkbcommon development files 1.6.0
 ✖ xkbcommon-x11 development files: pkg-config cannot find xkbcommon-x11
     Fix: Debian/Ubuntu: sudo apt install libxkbcommon-x11-dev, Fedora: sudo dnf install libxkbcommon-x11-devel, Arch: sudo pacman -S libxkbcommon-x11
 ✓ xcb development files 1.15

1 problem found.

Inside a React Native project, npx react-native doctor-desktop runs the same checks, and npx react-native doctor lists them in a Desktop section next to its own.

Troubleshooting

Package xkbcommon-x11 was not found: install libxkbcommon-x11-dev (Debian / Ubuntu), libxkbcommon-x11-devel (Fedora) or libxkbcommon-x11 (Arch).
cargo: command not found: restart the terminal, or run . "$HOME/.cargo/env".
Node is too old: node --version reports less than 22.13. Install a newer Node with nvm.

Next steps

Your environment is ready. Continue with Get Started to create and run your first app.

Development OS​

Installing dependencies​

Node and Rust​

Xcode​

Verifying your setup​

Troubleshooting​

Installing dependencies​

Install the tools​

Configure PATH​

Enable long paths​

Use the Developer PowerShell​

Verifying your setup​

Troubleshooting​

Installing dependencies​

System packages​

Node and Rust​

Verifying your setup​

Troubleshooting​

Next steps​

Development OS

Installing dependencies

Node and Rust

Xcode

Verifying your setup

Troubleshooting

Installing dependencies

Install the tools

Configure `PATH`

Enable long paths

Use the Developer PowerShell

Verifying your setup

Troubleshooting

Installing dependencies

System packages

Node and Rust

Verifying your setup

Troubleshooting

Next steps