This error occurs when node-gyp cannot locate a Python executable to compile native Node.js addons. Python is a required dependency for node-gyp to build C++ modules during npm package installation.
node-gyp is a build tool that compiles native Node.js addon modules written in C++. Many npm packages depend on native modules for performance-critical operations or to interface with system-level APIs. To compile these native addons, node-gyp requires Python to run its build scripts. When Python is not installed, not in the system PATH, or configured incorrectly, node-gyp fails with this error and npm install cannot complete. This error is particularly common on fresh system installations, in Docker containers without build dependencies, or when Python was installed but not added to the PATH environment variable.
Check if Python is available on your system:
python --version
# or
python3 --versionIf you get "command not found", Python is not installed or not in PATH.
Windows:
# Using Chocolatey
choco install python
# Or download from python.org
# Ensure "Add Python to PATH" is checked during installationmacOS:
# Using Homebrew
brew install python3Linux (Debian/Ubuntu):
sudo apt-get update
sudo apt-get install python3 python3-devLinux (RHEL/CentOS/Fedora):
sudo yum install python3 python3-develAfter installation, verify with python3 --version.
If Python is installed but node-gyp still can't find it, explicitly configure npm:
# Set Python path for npm (replace with your actual Python path)
npm config set python /usr/bin/python3
# On Windows
npm config set python "C:\Python39\python.exe"Alternatively, set the environment variable:
# Linux/macOS
export npm_config_python=/usr/bin/python3
# Windows (PowerShell)
$env:npm_config_python="C:\Python39\python.exe"node-gyp also requires C++ compilers and build tools:
Windows:
# Install Visual Studio Build Tools (run as Administrator)
npm install --global windows-build-tools
# Or install Visual Studio with "Desktop development with C++" workloadmacOS:
# Install Xcode Command Line Tools
xcode-select --installLinux:
# Debian/Ubuntu
sudo apt-get install build-essential
# RHEL/CentOS/Fedora
sudo yum groupinstall "Development Tools"After installing Python and build tools, try installing again:
# Clear npm cache
npm cache clean --force
# Reinstall with verbose output to see detailed logs
npm install --verboseThe verbose flag will show exactly where node-gyp is looking for Python.
You can specify the Python path directly when installing:
npm install --python=/usr/bin/python3
# Or for a specific package
npm install bcrypt --python=/usr/bin/python3This bypasses npm configuration and directly tells node-gyp which Python to use.
Python Version Compatibility:
node-gyp v10+ requires Python 3.6 or later. Older versions of node-gyp support Python 2.7, but Python 2 reached end-of-life in 2020 and should be avoided. If you're using an older Node.js version with an old node-gyp, consider upgrading Node.js rather than installing Python 2.
Docker Considerations:
When building Node.js applications in Docker, use base images that include build dependencies:
# Instead of node:alpine
FROM node:18-alpine
# Install Python and build tools
RUN apk add --no-cache python3 make g++
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=productionFor Debian-based images:
FROM node:18
RUN apt-get update && apt-get install -y \
python3 \
build-essential \
&& rm -rf /var/lib/apt/lists/*Pre-built Binaries Alternative:
Some packages offer pre-built binaries that don't require compilation. For example, @mapbox/node-pre-gyp downloads pre-compiled binaries when available. Check if your dependency offers this option to avoid the need for Python and build tools entirely.
Windows PATH Configuration:
On Windows, if Python is installed but not found, manually add it to PATH:
1. Search for "Environment Variables" in Windows Settings
2. Edit the "Path" variable under System Variables
3. Add the Python installation directory (e.g., C:\Python39 and C:\Python39\Scripts)
4. Restart your terminal/IDE
Multiple Python Versions:
If you have both Python 2 and Python 3 installed, node-gyp might pick the wrong one. Always explicitly configure which version to use via npm config set python or the --python flag.
CI/CD Configuration:
For GitHub Actions, GitLab CI, or other CI platforms, ensure your pipeline includes Python in the build environment:
# GitHub Actions
- uses: actions/setup-python@v4
with:
python-version: '3.10'
# GitLab CI
image: node:18
before_script:
- apt-get update && apt-get install -y python3 build-essentialError: Listener already called (once event already fired)
EventEmitter listener already called with once()
Error: EACCES: permission denied, open '/root/file.txt'
EACCES: permission denied
Error: Invalid encoding specified (stream encoding not supported)
How to fix Invalid encoding error in Node.js readable streams
Error: EINVAL: invalid argument, open
EINVAL: invalid argument, open
TypeError: readableLength must be a positive integer (stream config)
TypeError: readableLength must be a positive integer in Node.js streams