Installation & Setup

This guide covers everything you need to develop, build, and deploy Expo apps. Choose your setup based on what you’re building:

Quick start: Just Node.js and a phone → Use Expo Go
Full setup: Native builds → Install platform-specific tools

System Requirements

Required for All

Node.js 18 or newer
npm, yarn, or pnpm
Code editor (VS Code recommended)

For Native Builds

macOS (for iOS development)
Xcode 15+ (iOS)
Android Studio (Android)
CocoaPods (iOS)

Step 1: Install Node.js

Expo requires Node.js version 18 or newer.

macOS
Windows
Linux

Using Homebrew (recommended):

brew install node

Or download from nodejs.org:Visit nodejs.org and download the LTS version.Verify installation:

node --version  # Should show v18.0.0 or higher
npm --version

Download installer:Visit nodejs.org and download the LTS version for Windows.Or use winget:

winget install OpenJS.NodeJS

Verify installation:

node --version  # Should show v18.0.0 or higher
npm --version

You may need to restart your terminal after installation.

Using package manager:

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Fedora
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
sudo dnf install -y nodejs

Verify installation:

node --version  # Should show v18.0.0 or higher
npm --version

The Expo SDK requires Node.js 22.14.0 as specified in the monorepo, but Node 18+ is generally supported for app development.

Step 2: Install Expo CLI

Expo CLI is included with the expo package. You don’t need to install it globally!

npx create-expo-app my-app
cd my-app

Why no global install?

The @expo/cli package is versioned with the Expo SDK, ensuring compatibility. Running npx expo uses your project’s local version automatically.Benefits:

No version conflicts between projects
Automatic updates with SDK upgrades
Faster CI/CD (no global install needed)

Verify CLI Installation

npx expo --version

You should see output like:

55.0.9

Step 3: Platform-Specific Setup

iOS Development
Android Development
Web Development
Expo Go (No Build)

iOS development requires a Mac with macOS.

Install Xcode

Install Xcode from the Mac App Store (15+ required)
Open Xcode and accept the license agreement
Install command line tools:

xcode-select --install

Install CocoaPods

CocoaPods manages iOS native dependencies:

sudo gem install cocoapods

Or using Homebrew:

brew install cocoapods

Verify iOS Setup

# Check Xcode
xcodebuild -version

# Check CocoaPods
pod --version

# List available simulators
xcrun simctl list devices

Set Up iOS Simulator

Open the iOS Simulator:

open -a Simulator

In Xcode, go to Xcode → Settings → Platforms to download additional iOS versions.

Install Android Studio

Download from developer.android.com/studio
Run the installer and follow the setup wizard
Install the Android SDK through Android Studio

Configure Android SDK

In Android Studio:

Open Settings → Languages & Frameworks → Android SDK
Under SDK Platforms, install:
- Android 14 (API 34)
- Android 13 (API 33)
Under SDK Tools, install:
- Android SDK Build-Tools
- Android Emulator
- Android SDK Platform-Tools

Set Environment Variables

Add to your shell profile (~/.zshrc, ~/.bashrc, etc.):

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools

Windows: Add to System Environment Variables:

ANDROID_HOME: C:\Users\YourUsername\AppData\Local\Android\Sdk
Add to Path: %ANDROID_HOME%\platform-tools

Reload your shell:

source ~/.zshrc  # or ~/.bashrc

Verify Android Setup

# Check ADB
adb --version

# List available emulators
emulator -list-avds

Create Android Emulator

Open Android Studio
Go to Tools → Device Manager
Click Create Device
Select a device (e.g., Pixel 6)
Download and select a system image (e.g., Android 14)
Finish creation

Start an Emulator

# List available emulators
emulator -list-avds

# Start an emulator
emulator -avd Pixel_6_API_34

Web development requires no additional setup! Expo uses Metro bundler which includes web support.

Browser Requirements

Chrome, Firefox, Safari, or Edge (latest version)
JavaScript enabled
Local development: localhost access

Start Web Development

npx expo start --web

Or press w in the Expo dev server terminal.

Web-Specific Configuration

Configure web settings in app.json:

app.json

{
  "expo": {
    "web": {
      "bundler": "metro",
      "favicon": "./assets/favicon.png"
    }
  }
}

Step 4: Editor Setup

Visual Studio Code (Recommended)

Install VS Code Extensions:

Open VS Code
Install these extensions:
- ES7+ React/Redux/React-Native snippets
- React Native Tools
- Prettier - Code formatter
- ESLint

Configure VS Code: Create .vscode/settings.json in your project:

.vscode/settings.json

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

Step 5: Verify Installation

Create a test project to verify everything works:

Create test project

npx create-expo-app test-app
cd test-app

Start development server

npx expo start

Test on platforms

iOS Simulator (Mac only):

Press 'i' in the terminal

Android Emulator:

Press 'a' in the terminal

Web Browser:

Press 'w' in the terminal

Physical Device:

Scan QR code with Expo Go app

If your app opens successfully on any platform, your setup is complete!

Troubleshooting

iOS: 'command line tools are not installed'

Install Xcode command line tools:

xcode-select --install

If that doesn’t work, reset the path:

sudo xcode-select --reset

Android: 'ANDROID_HOME not set'

Add to your shell profile:

~/.zshrc

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools

Reload:

source ~/.zshrc

iOS: 'Unable to boot simulator'

Reset iOS Simulator:

Open Simulator app
Go to Device → Erase All Content and Settings
Try again

Or from command line:

xcrun simctl erase all

Android: 'No emulators found'

Create a new emulator in Android Studio:

Open Android Studio
Tools → Device Manager
Click Create Device
Follow the wizard

CocoaPods: 'pod install' fails

Update CocoaPods and try again:

sudo gem install cocoapods
cd ios
pod repo update
pod install

Node version issues

Use a Node version manager:nvm (Mac/Linux):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node 18
nvm install 18
nvm use 18

nvm-windows:Download from github.com/coreybutler/nvm-windows

Package Manager Choice

Expo works with npm, yarn, or pnpm:

npx create-expo-app my-app
npm install
npm start

Once you choose a package manager, stick with it for the entire project. Don’t mix them!

Next Steps

Quick Start

Create your first app in 5 minutes

Core Concepts

Learn how Expo works

Tutorial

Build a complete app step-by-step

Development Builds

Set up for custom native code

Introduction

Core Concepts

Creating Your First App

Installation & Setup

System Requirements

Required for All

For Native Builds

Step 1: Install Node.js

Step 2: Install Expo CLI

Verify CLI Installation

Step 3: Platform-Specific Setup

Install Xcode

Install CocoaPods

Verify iOS Setup

Set Up iOS Simulator

Install Android Studio

Configure Android SDK

Set Environment Variables

Verify Android Setup

Create Android Emulator

Start an Emulator

Browser Requirements

Start Web Development

Web-Specific Configuration

Install Expo Go on Your Device

What You Can Do

Limitations

Step 4: Editor Setup

Visual Studio Code (Recommended)

Step 5: Verify Installation

Troubleshooting

Package Manager Choice

Next Steps

Quick Start

Core Concepts

Tutorial

Development Builds

Build docs developers (and LLMs) love

Introduction

Core Concepts

Creating Your First App

Documentation Index

​System Requirements

Required for All

For Native Builds

​Step 1: Install Node.js

​Step 2: Install Expo CLI

​Verify CLI Installation

​Step 3: Platform-Specific Setup

​Install Xcode

​Install CocoaPods

​Verify iOS Setup

​Set Up iOS Simulator

​Install Android Studio

​Configure Android SDK

​Set Environment Variables

​Verify Android Setup

​Create Android Emulator

​Start an Emulator

​Browser Requirements

​Start Web Development

​Web-Specific Configuration

​Install Expo Go on Your Device

​What You Can Do

​Limitations

​Step 4: Editor Setup

​Visual Studio Code (Recommended)

​Step 5: Verify Installation

​Troubleshooting

​Package Manager Choice

​Next Steps

Quick Start

Core Concepts

Tutorial

Development Builds

Build docs developers (and LLMs) love

System Requirements

Step 1: Install Node.js

Step 2: Install Expo CLI

Verify CLI Installation

Step 3: Platform-Specific Setup

Install Xcode

Install CocoaPods

Verify iOS Setup

Set Up iOS Simulator

Install Android Studio

Configure Android SDK

Set Environment Variables

Verify Android Setup

Create Android Emulator

Start an Emulator

Browser Requirements

Start Web Development

Web-Specific Configuration

Install Expo Go on Your Device

What You Can Do

Limitations

Step 4: Editor Setup

Visual Studio Code (Recommended)

Step 5: Verify Installation

Troubleshooting

Package Manager Choice

Next Steps