Skip to content

How to Fix node-gyp Rebuild Errors on Linux/macOS/Windows

DodaTech 2 min read

In this tutorial, you'll learn about How to Fix node. We cover key concepts, practical examples, and best practices.

The Problem

You run npm install and get gyp ERR! build error or node-gyp rebuild fails. Native Node.js modules (like bcrypt, sharp, node-sass, better-sqlite3) need to compile C++ code during installation. A missing C++ compiler, Python, or build toolchain causes the build to fail. The error often appears as a wall of red text ending with gyp ERR! not ok. The specific tools needed vary by platform: Ubuntu and Debian need build-essential, macOS needs Xcode Command Line Tools, and Windows needs Visual Studio Build Tools. Without the correct toolchain for your OS, native modules cannot compile at all.

Quick Fix

1. Install build tools on Ubuntu/Debian

sudo apt-get update
sudo apt-get install build-essential python3 make g++ pkg-config

2. Install build tools on macOS

xcode-select --install

This installs the Xcode Command Line Tools, which include clang, make, and other build essentials.

3. Install build tools on Windows

# As Administrator
npm install --global windows-build-tools

# Or install Visual Studio Build Tools manually
# with "Desktop development with C++" workload

4. Set Python path for node-gyp

# node-gyp needs Python 3.x
npm config set python /usr/bin/python3

Check your Python version:

python3 --version

5. Clean and rebuild

# Clear node-gyp cache
npx node-gyp clean

# Rebuild a specific package
npm rebuild <package-name>

# Full clean reinstall
rm -rf node_modules package-lock.json
npm install

6. Check node-gyp configuration

npx node-gyp configure
npx node-gyp build

Look for specific error messages about missing tools.

7. Use alternative packages that don't require native compilation

// Instead of bcrypt (C++ addon), use bcryptjs (pure JS)
// Instead of sharp (C++ addon), consider jimp (pure JS)
// Instead of node-sass, use sass (dart-sass, pure JS)

8. Install node-gyp globally and set up

npm install -g node-gyp
node-gyp install  # Downloads platform-specific headers

Common Causes

Platform Missing Dependency Fix
Ubuntu/Debian build-essential, python3 sudo apt-get install build-essential python3
macOS Xcode CLT xcode-select --install
Windows VS Build Tools npm install -g <a href="/operating-systems/windows/">windows</a>-build-tools
Any Wrong Python version npm config set python /usr/bin/python3
Any node-gyp cache corrupted npx node-gyp clean then rebuild

Check Node.js and npm Versions

node --version
# v18.17.0
npm --version
# 9.6.7

Verify your runtime versions before troubleshooting module resolution or compatibility issues. Outdated versions of Node.js or npm are a common source of mysterious errors. Use nvm to manage multiple Node versions side by side.

Prevention

  • Install build tools before any native module installation
  • Use the LTS version of Node.js (native modules often lag behind latest)
  • Prefer WASM-based alternatives like bcryptjs instead of bcrypt to avoid native compilation

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro