What Does “react-scripts: command not found” Mean?

The error message sh: react-scripts: command not found (or variations like command not found: react-scripts on macOS) means your system cannot locate the react-scripts executable when you try to run your React application.

Understanding the Error Message

When you run a command like npm start or react-scripts start, here’s what happens:

1. Terminal searches for executable → Looks in your system PATH
2. Checks node_modules/.bin folder → Where npm packages store executables
3. If not found → Shows “command not found” error
4. Process fails → Your React app won’t start

What is react-scripts?

react-scripts is a build toolchain included with Create React App (CRA). It contains:

• Webpack → Bundles your code
• Babel → Transpiles JSX & ES6+ syntax
• Jest → Testing framework
• ESLint → Code linting
• Dev Server → Hot module reloading

Without it, you can’t run, build, or test your React application.

Why This Error Occurs (5 Root Causes)

Root Cause #1: react-scripts Not Installed (40% of cases)

Scenario: You cloned a GitHub repo or started a new project but skipped npm install.

# ❌ You ran:
npm start

# ❌ Without running first:
npm install  # ← Missing this step!

Why it happens:

• GitHub repos include .gitignore that excludes node_modules/
• node_modules is large (~300MB), so it’s never committed to Git
• You must install dependencies on every machine
• Moving projects between computers triggers this

Root Cause #2: node_modules Folder Deleted or Corrupted (35% of cases)

Scenario: Accidentally deleted node_modules or it got corrupted.

# ❌ Someone ran:
rm -rf node_modules  # Delete entirely

# ✅ Instead of:
npm ci  # Clean install (more reliable)

Why it happens:

• Developers delete it to free up disk space (250-500MB)
• Package updates fail partway through
• Disk corruption during installation
• Antivirus software interferes with package installation

Root Cause #3: node/npm Not Installed or Outdated (15% of cases)

Scenario: Node.js or npm is missing or using an incompatible version.

# Check if installed
node --version
npm --version

# If "command not found":
# Node/npm is NOT installed

Why it happens:

• Fresh machine setup without Node.js
• Used system npm (very old) instead of Node.js version
• Multiple Node.js versions installed; using wrong one

Root Cause #4: Wrong Working Directory (5% of cases)

Scenario: Running react-scripts outside your project root.

# ❌ You're in wrong directory:
/Users/dev/Projects$ npm start

# ✅ You need to be in:
/Users/dev/Projects/my-react-app$ npm start

Why it happens:

• Terminal session lost directory context
• Running command from parent directory
• Typo in directory path

Root Cause #5: Global vs. Local Installation Conflict (5% of cases)

Scenario: react-scripts installed globally but not locally.

# ❌ Installed globally (old practice):
npm install -g react-scripts

# ✅ Modern approach (local):
npm install react-scripts  # Per-project installation

Why it matters:

• Global installations can cause version conflicts
• Different projects need different versions
• npm best practice: always install locally

Solution 1: Install Missing react-scripts Package

Fixes: Root Causes #1, #2
Difficulty: ⭐ (Easiest)
Time: 2-5 minutes

Step-by-Step

Step 1: Open Terminal in Project Root

Navigate to your React project directory (where package.json lives):

cd /path/to/your/react-project

Verify you’re in the right place:

ls  # Should see: package.json, src/, public/, node_modules/, etc.

Step 2: Install All Dependencies

# Standard install (recommended)
npm install

# OR if using Yarn:
yarn install

# OR if using pnpm:
pnpm install

What this does:

• Reads package.json
• Downloads all packages from npmjs.com
• Creates node_modules/ folder
• Installs react-scripts inside node_modules/.bin/

Step 3: Verify Installation

# Check if react-scripts exists
npm ls react-scripts

# Expected output:
# └── react-scripts@5.0.1

Step 4: Start Your App

npm start

Your React dev server should now run on http://localhost:3000

Faster Alternative: npm ci (Clean Install)

If npm install is slow or keeps failing, use clean install:

# Remove lock file (if corrupted)
rm package-lock.json

# Clean install from scratch
npm ci

Why npm ci is better for CI/CD:

• Installs exact versions from package-lock.json
• Faster than npm install
• More reliable on shared machines
• Prevents version drift

Solution 2: Fix Missing node_modules Folder

Fixes: Root Causes #2
Difficulty: ⭐ (Easiest)
Time: 3-10 minutes (depends on internet speed)

Step-by-Step

Step 1: Verify node_modules is Missing

ls -la  # On Mac/Linux
dir    # On Windows

# Should see:
# node_modules (does NOT exist? → This is the problem)

Step 2: Full Reinstall

# Remove package lock (to start fresh)
rm package-lock.json

# Full reinstall
npm install

Step 3: If Still Failing, Clear npm Cache

# Clear npm cache entirely
npm cache clean --force

# Then try again
npm install

Next 4: Verify Installation

# Check react-scripts is present
ls node_modules/.bin/ | grep react-scripts

# Expected: react-scripts (executable file)

Troubleshooting Installation Failures

If installation hangs or fails:

# Try with specific registry (faster in some regions)
npm install --registry https://registry.npmjs.org/

# Try with legacy peer deps (for old projects)
npm install --legacy-peer-deps

# Try with network timeout increased
npm install --network-timeout 60000

Solution 3: Update Your System PATH {#solution-3}

Fixes: Root Causes #3, #5
Difficulty: ⭐⭐ (Intermediate)
Time: 5-10 minutes

What is PATH?

Your system PATH is a list of directories where your terminal looks for executables:

# View your current PATH
echo $PATH

# Example output:
# /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

When you type react-scripts, the terminal searches these directories in order.

Add node_modules/.bin to PATH

Option A: For Current Session Only (Temporary)

# macOS/Linux - Add to PATH for this session
export PATH="./node_modules/.bin:$PATH"

# Windows (PowerShell)
$env:Path = ".\node_modules\.bin;$env:Path"

# Now try:
npm start

Note: This only works for the current terminal session. Close terminal = reset.

Option B: Permanent (Recommended)

For macOS/Linux:

1. Open shell config file:

# For Zsh (macOS 10.15+):
nano ~/.zshrc

# For Bash (older macOS/Linux):
nano ~/.bashrc

# For Fish shell:
nano ~/.config/fish/config.fish

2. Add this line:

export PATH="./node_modules/.bin:$PATH"

3. Save & reload:

# Save (in nano): Ctrl+X → Y → Enter

# Reload shell config
source ~/.zshrc

For Windows:

1. Right-click Start → Search “Environment Variables”
2. Click “Edit Environment Variables for your account”
3. Click “New” → Add this path:

C:\Users\YourUsername\AppData\Roaming\npm

4. Click OK twice → Restart terminal

Verify PATH Configuration

# Check if npm/node are in PATH
which node
which npm

# Expected output:
# /usr/local/bin/node
# /usr/local/bin/npm

Solution 4: Clear Cache & Reinstall Dependencies {#solution-4}

Fixes: Root Causes #2, #3 (corrupted installations)
Difficulty: ⭐ (Easiest)
Time: 5-15 minutes

Complete Clean Slate Approach

When dependencies are corrupted or stuck, nuke everything and restart:

# Step 1: Delete node_modules
rm -rf node_modules

# Step 2: Delete lock file (for consistent reinstall)
rm package-lock.json

# Step 3: Clear npm cache
npm cache clean --force

# Step 4: Check npm version (update if needed)
npm --version
npm install -g npm@latest  # Update npm itself

# Step 5: Fresh install
npm install

Windows equivalent:

# Step 1: Delete node_modules
rmdir /s /q node_modules

# Step 2: Delete lock file
del package-lock.json

# Step 3-4: Same as above
npm cache clean --force
npm install -g npm@latest

# Step 5: Fresh install
npm install

When to Use This Approach

✅ Use when:

• npm start fails for unknown reasons
• npm error messages are cryptic
• Installation hangs or times out
• Multiple npm commands are failing

❌ Avoid when:

• You have custom modifications in node_modules (don’t—use local patches instead)
• You’re on a very slow connection
• Disk space is critically low

Solution 5: Use npm Scripts Instead of Direct Commands {#solution-5}

Fixes: Root Causes #1, #5
Difficulty: ⭐ (Easiest conceptually)
Best Practice: Always do this

Why npm Scripts Are Better

Direct invocation:

# ❌ Don't do this:
react-scripts start

# Problems:
# - Requires react-scripts in PATH
# - Global installations cause conflicts
# - Version mismatches between projects

npm scripts approach:

# ✅ Do this instead:
npm start

# Benefits:
# - Works with local installations
# - No PATH issues
# - Uses exact version in package.json
# - Consistent across all developers

Using npm Scripts Properly

In your package.json:

{
  "name": "my-react-app",
  "version": "1.0.0",
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-scripts": "5.0.1"
  }
}

From terminal:

npm start   # Runs: react-scripts start
npm run build  # Runs: react-scripts build
npm test    # Runs: react-scripts test

Why This Works

When you run npm start:

1. npm finds your package.json
2. Looks for "start": "react-scripts start" script
3. Automatically adds ./node_modules/.bin to PATH temporarily
4. Runs react-scripts from that location
5. No global installation needed

Custom npm Scripts

Create your own scripts for common tasks:

{
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "dev": "react-scripts start --port 3001",
    "format": "prettier --write \"src/**/*.{js,jsx,css}\"",
    "lint": "eslint src/",
    "analyze": "npm run build -- --stats"
  }
}

Then use:

npm run dev      # Start on custom port
npm run format   # Format code
npm run lint     # Check code quality
npm run analyze  # Build analysis

Platform-Specific Fixes (Windows, Mac, Linux) {#platform-specific}

Windows-Specific Solutions

Problem: PowerShell execution policy blocks npm

# If npm doesn't run in PowerShell:
# Error: "cannot be loaded because running scripts is disabled"

# Solution: Enable execution policy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Then try:
npm start

Problem: Paths with spaces fail

# ❌ Fails:
cd C:\Users\My Projects\my-app

# ✅ Works:
cd "C:\Users\My Projects\my-app"

# Or use short paths:
cd C:\Users\~1\MYPRO~1\my-app

Error: Antivirus blocks npm installation

• Temporarily disable antivirus during npm install
• Add npm cache to antivirus whitelist: %LocalAppData%\npm-cache
• Add Node.js to antivirus whitelist: C:\Program Files\nodejs

macOS-Specific Solutions

Problem: “Permission denied” errors

# Don't use sudo with npm (causes permission issues)
# ❌ Don't do:
sudo npm install

# ✅ Do instead:
npm install

# If you get permission errors, fix npm permissions:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
source ~/.zshrc

Problem: npm not found after installing Node.js

# Reinstall Node.js (npm comes with it)
# Download from: https://nodejs.org/

# Verify installation:
node --version
npm --version

Linux-Specific Solutions

Problem: Permission denied (common on Ubuntu/Debian)

# Don't use sudo with npm
# ✅ Fix permissions instead:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

# Add to ~/.bashrc or ~/.zshrc:
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Problem: Using system npm (very old)

# Don't use: sudo apt-get install npm (outdated)
# Instead, install Node.js:

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

# Verify:
node --version
npm --version

Vite Alternative (Recommended for New Projects) {#vite-alternative}

Context: When you install React in VS Code, you now have a choice: Create React App (CRA) vs. Vite

CRA with react-scripts is slower and more problematic than modern alternatives. Consider Vite for new projects:

CRA (Create React App) vs. Vite Comparison

Feature	Create React App	Vite
Startup Speed	30-45 seconds	2-5 seconds
Build Time	2-5 minutes	10-30 seconds
File Size	Larger (bloated)	Smaller
react-scripts Errors	Common	None (no react-scripts)
Hot Reload	Slow	Instant
Setup Complexity	Moderate	Simple
Modern Stack	Webpack (outdated)	Esbuild/Rollup (modern)

Create New React Project with Vite

# Instead of: npx create-react-app my-app
# ✅ Use:
npm create vite@latest my-app -- --template react

# Then:
cd my-app
npm install
npm run dev  # Starts on http://localhost:5173

Convert Existing CRA Project to Vite

Step 1: Create new Vite project

npm create vite@latest my-app-vite -- --template react
cd my-app-vite
npm install

Step 2: Copy your src folder

# Copy your existing source code to new project
cp -r ../my-cra-app/src ./src

Step 3: Update environment variables (if used)

In Vite, environment variables use import.meta.env instead of process.env:

// CRA:
process.env.REACT_APP_API_URL

// Vite:
import.meta.env.VITE_API_URL

// .env file (same for both):
VITE_API_URL=http://localhost:5000

Step 4: Update imports (if needed)

// Some imports might need adjustment
// Vite is stricter about file extensions
import MyComponent from './MyComponent.jsx'  // Add .jsx

Benefits of switching:

• No more react-scripts: command not found errors
• 10x faster development (instant hot reload)
• Significantly faster builds
• Smaller bundle size
• Modern JavaScript tooling

Troubleshooting Decision Tree

Use this flowchart when react-scripts errors occur:

┌─ Did you just clone a repo or create new project?
│  ├─ YES → Run: npm install
│  └─ NO ↓
│
├─ Does node_modules folder exist?
│  ├─ NO → Run: npm install
│  ├─ YES, but small (<100MB)? → Folder corrupted
│  │  └─ Run: rm -rf node_modules && npm install
│  └─ YES, normal size? ↓
│
├─ Run: npm ls react-scripts
│  ├─ Shows "not installed"? → Run: npm install react-scripts
│  ├─ Shows version? → Proceed ↓
│  └─ Shows error? → npm cache clean --force && npm install
│
├─ Which directory are you in?
│  ├─ NOT in project root? → cd to correct directory
│  └─ In project root? ↓
│
├─ Try: npm start
│  ├─ WORKS? → Success! ✅
│  ├─ Still fails? → Try: npm run build
│  │  └─ If build works → Dev server issue (Vite switch recommended)
│  └─ Nothing works? → Final troubleshoot ↓
│
└─ Final steps:
   ├─ Update Node.js: https://nodejs.org/
   ├─ Clear cache: npm cache clean --force
   ├─ Full reinstall: rm -rf node_modules && npm install
   └─ Still stuck? → Consider migrating to Vite

Preventing Future Errors {#prevention}

1. Use .gitignore Correctly

Always exclude node_modules:

# .gitignore
node_modules/
node_modules
.pnp
.pnp.js
npm-debug.log

Why: node_modules is large; Git doesn’t need it.

2. Commit Lock File to Version Control

Always commit:

• ✅ package.json
• ✅ package-lock.json (npm) or yarn.lock (Yarn)
• ❌ node_modules/

Why: Lock files ensure consistent versions across machines

git add package.json package-lock.json
git commit -m "Update dependencies"

3. Use npm ci in CI/CD

For automated testing/deployment:

# In your CI pipeline (GitHub Actions, Jenkins, etc.):
npm ci  # Clean install (faster, more reliable than npm install)
npm run build
npm test

4. Regular Dependency Updates

Keep packages fresh to prevent version conflicts:

# Check for outdated packages
npm outdated

# Update packages safely
npm update

# Or update to latest versions (may break compatibility)
npm install

5. Document Setup in README

Help team members avoid this error:

## Setup Instructions

1. Clone the repository:
   git clone <repo-url>

2. Install dependencies:
   npm install

3. Start development server:
   npm start

4. Build for production:
   npm run build

## Troubleshooting

If you see "react-scripts: command not found":
1. Verify Node.js and npm are installed: node --version && npm --version
2. Reinstall dependencies: npm install
3. Clear cache: npm cache clean --force

FAQs

Q: “react-scripts: command not found” but npm ls react-scripts shows it’s installed?

A: Your shell’s PATH is cached. Restart your terminal or run:

# Refresh shell environment
exec $SHELL

# Or manually add to PATH:
export PATH="./node_modules/.bin:$PATH"

Q: Why can’t I use react-scripts with sudo?

A: Don’t use sudo with npm. It causes permission issues:

# ❌ Wrong:
sudo npm install
sudo npm start

# ✅ Correct:
npm install
npm start

# If permission errors occur, fix npm permissions instead

Q: Is npm install -g react-scripts a good solution?

A: No. Global installations cause version conflicts. Always install locally:

# ❌ Avoid:
npm install -g react-scripts

# ✅ Use:
npm install react-scripts  # Local to project
npm start  # Uses local version

Q: Does Vite have react-scripts?

A: No. Vite doesn’t use react-scripts. It uses modern tooling (Esbuild/Rollup). This is actually a benefit—no more react-scripts errors:

# Vite doesn't have this error
npm run dev  # Always works if dependencies installed

Q: Can I fix this error without reinstalling node_modules?

A: Sometimes. Try these first before full reinstall:

# 1. Update npm itself
npm install -g npm@latest

# 2. Rebuild native packages
npm rebuild

# 3. Verify installation
npm ls react-scripts

# 4. Only if above fails:
rm -rf node_modules && npm install

Q: “npm install” itself is failing. What do I do?

A: Your npm installation is broken. Fix npm:

# Clear npm cache
npm cache clean --force

# Reinstall npm
npm install -g npm@latest

# Or reinstall Node.js entirely from https://nodejs.org/

Q: I’m offline. Can I use react-scripts without npm?

A: No. npm packages are cloud-based. Options:

# 1. Use npm offline (requires prior download):
npm install --offline

# 2. Use Yarn with offline cache:
yarn install --offline

# 3. Best solution: Get internet connection and install dependencies

Related Resources & Next Steps

Ready to eliminate setup errors completely? Explore these guides in your React setup cluster:

• How to Install React JS in Visual Studio Code — Start here if you’re setting up a new project
• What is npm in React? — Understand package management for installing CORS
• How to Create Routes in React JS — Build multi-page apps with backend API calls
• How to Upload Files in React JS — Handle file uploads with CORS
• React Best Practices to Up Your Game in 2023 — Write secure, maintainable code
• React Developer Tools in Chrome — Debug API calls and component state
• Troubleshooting “sh: react-scripts: command not found — Fix common React setup errors

Conclusion

The sh: react-scripts: command not found error is frustrating but usually fixable in 2-5 minutes with these solutions:

✅ 90% of cases: Run npm install
✅ Most other cases: Clear cache + reinstall
✅ Still broken: Add node_modules/.bin to PATH
✅ Persistent issues: Switch to Vite (recommended for new projects)

Key takeaway: Use npm scripts (npm start) instead of direct commands (react-scripts start). This single practice prevents this entire class of errors.

When first setting up React, follow the step-by-step VS Code installation guide to avoid these issues entirely.