How to Fix node-gyp Native Compilation Errors When Installing NPM Packages

✨ Quick Answer

The NPM package installation error node-gyp rebuild failed or make: *** [addon.target.mk] Error 1 occurs when a Node.js dependency requires compiling native add-ons written in C or C++ (such as bcrypt, sharp, or sqlite3) and your operating system lacks a compatible C++ compiler or Python in its global environment path.

Quick Diagnostics

Cause

Missing C/C++ build tools (make, gcc, python3) on system

Solution

Install dev tools: sudo apt install build-essential or pacman -S base-devel

Cause

Node.js version too recent for legacy native C++ modules

Solution

Use NVM to temporarily switch to an LTS Node.js release

The NPM package installation error node-gyp rebuild failed or make: *** [addon.target.mk] Error 1 occurs when a Node.js dependency requires compiling native add-ons written in C or C++ (such as bcrypt, sharp, or sqlite3) and your operating system lacks a compatible C++ compiler or Python in its global environment path.

Step-by-Step Solution

1. 1

   Step 1: Install build tools on your operating system

   Install the required C++ compilers (make, g++, gcc), Python, and base development packages:

   BASH Copy

   # For Debian / Ubuntu based systems
   sudo apt update && sudo apt install -y build-essential python3
   
   # For Arch Linux / CachyOS based systems
   sudo pacman -Syu base-devel python
   

2. 2

   Step 2: Clear and reset node-gyp cache

   A corrupted or outdated Node.js build cache can cause compilation failures during module rebuilding:

   BASH Copy

   # Clear NPM cache forcefully
   npm cache clean --force
   
   # Force rebuild of native modules locally
   npm rebuild
   

3. 3

   Step 3: Configure Python path for node-gyp

   If node-gyp cannot locate the correct Python interpreter on your system, define it explicitly in NPM's configuration:

   BASH Copy

   # Set the global path to the Python interpreter for NPM
   npm config set python /usr/bin/python3