The prebuild-install ELIFECYCLE error occurs when npm fails to download prebuilt binaries and then fails to compile from source. Install build tools (Python, C++ compiler) to enable fallback compilation.
Fixes npm ERR! code ELIFECYCLE npm ERR! errno 1 npm ERR! prebuild-install
xcode-select --installxcode-select --installnpm ERR! code ELIFECYCLEnpm ERR! errno 1npm ERR! prebuild-install
On this page
The prebuild-install error occurs during installation of native Node.js modules that contain C++ code. These packages use a two-step installation process: first, prebuild-install attempts to download precompiled binaries for your platform; if that fails, it falls back to compiling from source using node-gyp. When you see this error, it means both steps failed—no prebuilt binary was available for your platform/Node version combination, and the source compilation also failed due to missing build tools (Python, C++ compiler, make) or other compilation errors.
Native modules need compilation tools when prebuilt binaries aren't available:
macOS:
xcode-select --installUbuntu/Debian:
sudo apt-get update
sudo apt-get install build-essential python3Windows:
# Run as Administrator
npm install -g windows-build-tools
# Or install Visual Studio Build Tools manuallyAlpine Linux (Docker):
RUN apk add --no-cache python3 make g++ gccReset npm state and try again:
# Clear npm cache
npm cache clean --force
# Remove existing installation
rm -rf node_modules package-lock.json
# Reinstall
npm installPrebuilt binaries may not exist for very new Node.js versions:
# Check your version
node -v
# Try an LTS version if on bleeding edge
nvm install --lts
nvm use --lts
# Reinstall packages
rm -rf node_modules && npm installExplicitly rebuild native modules:
# Rebuild all native modules
npm rebuild
# Rebuild specific package from source
npm rebuild sharp --build-from-source
npm rebuild bcrypt --build-from-sourceIf Python isn't found automatically:
# Set Python path globally
npm config set python /usr/bin/python3
# Or set environment variable
export npm_config_python=/usr/bin/python3
npm installCompilation can fail with insufficient memory:
# Increase Docker memory to 4GB+
# Docker Desktop: Settings → Resources → Memory
# Or run with memory flag
docker run --memory=4g ...Common packages that use prebuild-install: sharp (image processing), bcrypt (password hashing), canvas, leveldown, sqlite3, and serialport.
For production, consider pure JavaScript alternatives that don't require native compilation:
- bcrypt → bcryptjs
- node-sass → sass (Dart Sass)
- sharp → jimp (slower but pure JS)
Modern packages are migrating to prebuildify + node-gyp-build, which ships all binaries inside the npm package, eliminating the download step entirely. Packages using this approach are more reliable across platforms.