How to fix npm ERR! command failed npm ERR! command sh -c node-gyp rebuild in npm

npmINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 268 views

The node-gyp rebuild error occurs when compiling native C++ modules fails. Install platform-specific build tools (Python, C++ compiler) to resolve this error.

Quick fix

Fixes npm ERR! command failed npm ERR! command sh -c node-gyp rebuild

xcode-select --install
  1. Install build tools for your platform
  2. Configure Python path
  3. Update node-gyp
  4. Clean and reinstall
npm — error
xcode-select --install
npm ERR! command failed
npm ERR! command sh -c node-gyp rebuild

What this error means

Node-gyp is a build tool that compiles native Node.js addons written in C/C++. This error occurs when node-gyp fails to compile a package's native code during npm install. The error typically indicates missing build tools—node-gyp requires Python and a C++ compiler to compile native modules. Different platforms need different tools: Visual Studio on Windows, Xcode on macOS, and build-essential on Linux.

Typical symptoms

  • npm install fails with "node-gyp rebuild" error
  • Error shows "gyp ERR!" messages
  • Installation halts during native module compilation
  • Works on some machines but fails on others
  • Error occurs with packages like bcrypt, canvas, sqlite3, node-sass
  • Fails after Node.js or OS upgrade

Common causes

  1. Missing C++ compiler (Visual Studio, Xcode, gcc)
  2. Missing or wrong Python version
  3. Node.js version incompatible with native module
  4. Permission issues running npm as sudo
  5. Outdated node-gyp version
  6. Missing Windows SDK or macOS Command Line Tools

How to fix "npm ERR! command failed npm ERR! command sh -c node-gyp rebuild"

1Install build tools for your platform

Each platform needs specific tools:

macOS:

bash
xcode-select --install

Ubuntu/Debian:

bash
sudo apt-get update
sudo apt-get install build-essential python3

Windows (run as Administrator):

bash
npm install -g windows-build-tools

Or install Visual Studio 2022 with "Desktop development with C++" workload.

Alpine Linux (Docker):

dockerfile
RUN apk add --no-cache python3 make g++
2Configure Python path

Node-gyp requires Python 3.6+:

bash
# Check Python version
python3 --version

# Set Python path for npm
npm config set python /usr/bin/python3

# Or use environment variable
export npm_config_python=/usr/bin/python3

Windows users should ensure Python is in PATH.

3Update node-gyp

Ensure you have the latest node-gyp:

bash
# Update global node-gyp
npm install -g node-gyp@latest

# Verify version
node-gyp --version
4Clean and reinstall

Clear cached builds and reinstall:

bash
# Remove node_modules and lockfile
rm -rf node_modules package-lock.json

# Clear npm cache
npm cache clean --force

# Reinstall
npm install
5Try a compatible Node.js version

Native modules are compiled for specific Node versions:

bash
# Use nvm to switch versions
nvm install 18
nvm use 18

# Reinstall after switching
rm -rf node_modules && npm install

LTS versions generally have better native module support.

6Fix permissions (Linux/macOS)

Avoid using sudo with npm:

bash
# Create npm global directory
mkdir -p ~/.npm-global

# Configure npm to use it
npm config set prefix '~/.npm-global'

# Add to PATH
export PATH=~/.npm-global/bin:$PATH

Add the export line to ~/.bashrc or ~/.zshrc.

7Reset Xcode on macOS

After macOS upgrades, Xcode may need reset:

bash
sudo xcode-select --reset
sudo xcode-select --install

Advanced notes

Common packages requiring node-gyp: bcrypt, sqlite3, canvas, sharp, node-sass (deprecated), serialport.

For production, consider pure JavaScript alternatives:
- bcrypt → bcryptjs
- node-sass → sass (Dart Sass)
- sqlite3 → better-sqlite3 or sql.js

On Apple Silicon Macs (M1/M2), ensure you're using the correct architecture Node.js binary. Rosetta can cause issues with native modules.

For Docker builds, always install build tools in the Dockerfile before npm install.

Frequently asked questions

What does "npm ERR! command failed npm ERR! command sh -c node-gyp rebuild" mean?
js addons written in C/C++. This error occurs when node-gyp fails to compile a package's native code during npm install. The error typically indicates missing build tools—node-gyp requires Python and a C++ compiler to compile native modules.
How do I fix "npm ERR! command failed npm ERR! command sh -c node-gyp rebuild"?
The node-gyp rebuild error occurs when compiling native C++ modules fails. Install platform-specific build tools (Python, C++ compiler) to resolve this error.
What causes "npm ERR! command failed npm ERR! command sh -c node-gyp rebuild"?
Missing C++ compiler (Visual Studio, Xcode, gcc) Missing or wrong Python version Node.js version incompatible with native module
Is the "npm ERR! command failed npm ERR! command sh -c node-gyp rebuild" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading