How to fix Error: No compiler found (node-gyp requires C++ compiler) in Node.js

Node.jsINTERMEDIATEHIGHUpdated Dec 9, 2025· 134 views

This error occurs when node-gyp cannot find a C++ compiler on your system. node-gyp is a tool used by Node.js packages to compile native C++ modules. It requires a C++ compiler (like g++ on Linux, clang on macOS, or Visual Studio on Windows) to be installed and properly configured.

Quick fix

Fixes GYPERR_COMPILER_NOT_FOUND

sudo apt-get update
sudo apt-get install build-essential python3
  1. Install build tools for your operating system
  2. Verify Python is installed and accessible
  3. Clear npm cache and retry installation
  4. Check node-gyp configuration and setup
node.js — error
sudo apt-get update
sudo apt-get install build-essential python3
Error: No compiler found (node-gyp requires C++ compiler)

What this error means

node-gyp is a cross-platform command-line tool written in Node.js for compiling native C++ modules for Node.js. When a package requires native compilation (common for performance-critical modules like sqlite3, bcrypt, or sharp), npm runs node-gyp to build the C++ extension. This error means the system is missing the required C++ compiler tools. node-gyp attempts to detect available compilers during the build process, but if none are found (or they're not in the PATH), the build fails with this error. The error is not a problem with your Node.js installation, but rather that your system lacks the development tools needed to compile native modules. Different operating systems require different toolchains to be installed.

Typical symptoms

  • npm install fails with "No compiler found" when installing packages with native dependencies
  • Error message includes "node-gyp rebuild" failed
  • Installation works on some machines but fails on others
  • Packages like sqlite3, bcrypt, or sharp fail to install
  • gyp ERR! appears in the build output
  • Error occurs specifically when running npm install on a fresh system or container

Common causes

  1. No C++ compiler toolchain installed on the system (g++, clang, Visual Studio Build Tools, etc.)
  2. C++ compiler is installed but not in the system PATH environment variable
  3. Visual Studio Build Tools or Python not properly configured on Windows
  4. Missing development headers or libraries required by node-gyp
  5. Command Line Tools for Xcode not installed on macOS
  6. build-essential package not installed on Linux systems
  7. Outdated or incompatible version of node-gyp installed globally
  8. Node.js version incompatible with available compiler version

How to fix "Error: No compiler found (node-gyp requires C++ compiler)"

1Install build tools for your operating system

The first step is to install a C++ compiler appropriate for your OS:

On Ubuntu/Debian:

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

On Fedora/RHEL:

bash
sudo dnf install gcc gcc-c++ make python3

On macOS:

bash
xcode-select --install

On Windows, download Visual Studio Build Tools from https://visualstudio.microsoft.com/downloads/ and select "Desktop development with C++" workload.

Verify the compiler is available:

bash
which g++
2Verify Python is installed and accessible

node-gyp requires Python (version 2.7 or 3.5+) to generate the build files. Check that Python is installed:

bash
python --version
python3 --version

If Python is not found, install it:

On Ubuntu/Debian:

bash
sudo apt-get install python3

On macOS:

bash
brew install python3

After installation, verify it's in your PATH by restarting your terminal.

3Clear npm cache and retry installation

Sometimes npm cache can cause issues. Clear it and retry:

bash
npm cache clean --force
npm install

If you're installing a specific package with native dependencies:

bash
npm install <package-name> --build-from-source

This forces npm to rebuild the native module.

4Check node-gyp configuration and setup

Verify that node-gyp is properly configured for your system:

bash
npm config get python
npm config get cc
npm config get cxx
npm config get make

If paths are missing or incorrect, set them manually:

bash
npm config set python /usr/bin/python3
npm config set python /usr/bin/python3 --global

On Windows with Visual Studio:

bash
npm config set msvs_version 2019
5Update Node.js and npm to compatible versions

Incompatible Node.js versions can cause compiler detection issues. Check your current versions:

bash
node --version
npm --version

Update to the latest LTS version. Using nvm (recommended):

bash
nvm install node
nvm use node

After updating, retry the installation:

bash
npm install
6Use precompiled binaries when available

Some packages provide precompiled binaries for common systems, avoiding the need to compile locally:

bash
npm install <package-name> --ignore-scripts

However, this only works if a prebuilt binary is available for your Node.js version and platform.

For some packages, you can specify prebuilt versions:

bash
npm install sqlite3 --build-from-source=false

Check the package documentation to see if prebuilt binaries are available.

Advanced notes

Docker and Containers: When building Docker images, ensure the compiler toolchain is installed. In the Dockerfile, run: apt-get update && apt-get install -y build-essential python3

CI/CD Pipelines: Ensure your CI configuration installs build tools before running npm install. For GitHub Actions, add a step: sudo apt-get update && sudo apt-get install -y build-essential

Custom node-gyp Builds: If you're developing a native module, test the build manually with: node-gyp configure and node-gyp build. For detailed output, use: node-gyp build --verbose

WSL (Windows Subsystem for Linux): Install tools in the Linux environment, not Windows. Run: sudo apt-get install build-essential python3

Cross-Compilation: For advanced scenarios where you're compiling on one system for another, use the target-arch flag: npm install --target_arch=x64 --target_platform=linux

Frequently asked questions

What does "GYPERR_COMPILER_NOT_FOUND" mean?
js. When a package requires native compilation (common for performance-critical modules like sqlite3, bcrypt, or sharp), npm runs node-gyp to build the C++ extension. This error means the system is missing the required C++ compiler tools.
How do I fix "GYPERR_COMPILER_NOT_FOUND"?
This error occurs when node-gyp cannot find a C++ compiler on your system. node-gyp is a tool used by Node.js packages to compile native C++ modules. It requires a C++ compiler (like g++ on Linux, clang on macOS, or Visual Studio on Windows) to be installed and properly configured.
What causes "GYPERR_COMPILER_NOT_FOUND"?
No C++ compiler toolchain installed on the system (g++, clang, Visual Studio Build Tools, etc.) C++ compiler is installed but not in the system PATH environment variable Visual Studio Build Tools or Python not properly configured on Windows
Is the "GYPERR_COMPILER_NOT_FOUND" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading