How to fix npm ERR! bcrypt@5.0.1 install: node-pre-gyp install --fallback-to-build in npm

npmINTERMEDIATEMEDIUMUpdated Dec 3, 2025· 143 views

This error occurs when bcrypt can't find prebuilt binaries and attempts to compile from source without necessary build tools. Install build dependencies or consider using bcryptjs as a pure JavaScript alternative.

Quick fix

Fixes npm ERR! bcrypt@5.0.1 install: node-pre-gyp install --fallback-to-build

sudo apt-get update
sudo apt-get install -y build-essential python3
  1. Install build tools on Ubuntu/Debian
  2. Install build tools on CentOS/RHEL
  3. Install build tools on Alpine
  4. Retry bcrypt installation
npm — error
sudo apt-get update
sudo apt-get install -y build-essential python3
npm ERR! bcrypt@5.0.1 install: node-pre-gyp install --fallback-to-build

What this error means

bcrypt is a password hashing library with native C++ bindings for performance. It first tries to download prebuilt binaries for your platform. When that fails, it falls back to building from source using node-pre-gyp. This error occurs when both approaches fail - usually because build tools (gcc, g++, make, python) are missing from your system. bcrypt requires native compilation because the computationally intensive hashing algorithm is implemented in C++ for security and performance reasons.

Typical symptoms

  • npm install bcrypt fails with node-pre-gyp errors
  • Build process mentions missing python, gcc, or make
  • Error includes "gyp ERR!" messages
  • Installation works on development machine but fails in Docker/CI
  • Prebuilt binary download fails with 404 or network error

Common causes

  1. Build tools (gcc, g++, make) not installed
  2. Python not installed or not in PATH
  3. node-gyp not properly configured
  4. Prebuilt binaries not available for Node.js/platform combination
  5. Network issues preventing binary download

How to fix "npm ERR! bcrypt@5.0.1 install: node-pre-gyp install --fallback-to-build"

1Install build tools on Ubuntu/Debian

Install the required build dependencies:

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

This includes gcc, g++, make, and other compilation tools.

2Install build tools on CentOS/RHEL

For Red Hat-based systems:

bash
sudo yum groupinstall -y "Development Tools"
sudo yum install -y python3
3Install build tools on Alpine

For Alpine Linux (Docker):

bash
apk add --no-cache build-base python3
4Retry bcrypt installation

After installing build tools:

bash
npm install bcrypt

Or rebuild existing installation:

bash
npm rebuild bcrypt
5Alternative: Use bcryptjs instead

If native compilation is problematic, use the pure JavaScript version:

bash
npm uninstall bcrypt
npm install bcryptjs

Update your imports:

javascript
// Before
const bcrypt = require('bcrypt');

// After (API compatible)
const bcrypt = require('bcryptjs');

bcryptjs is slower but has no native dependencies.

Advanced notes

For Docker builds, add build tools in a multi-stage build:

dockerfile
FROM node:20-alpine AS builder
RUN apk add --no-cache build-base python3
WORKDIR /app
COPY package*.json ./
RUN npm ci

FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .

bcrypt vs bcryptjs comparison:
- bcrypt: ~100x faster, requires compilation
- bcryptjs: Pure JS, no native deps, slower but acceptable for most apps

For CI/CD pipelines, caching the node_modules after successful bcrypt compilation can save time on subsequent runs.

If you're using an uncommon platform/architecture, bcrypt may not have prebuilt binaries. Check https://github.com/kelektiv/node.bcrypt.js for supported platforms.

Set the Python path explicitly if needed:

bash
npm config set python /usr/bin/python3

Frequently asked questions

What does "npm ERR! bcrypt@5.0.1 install: node-pre-gyp install --fallback-to-buil" mean?
bcrypt is a password hashing library with native C++ bindings for performance. It first tries to download prebuilt binaries for your platform. When that fails, it falls back to building from source using node-pre-gyp.
How do I fix "npm ERR! bcrypt@5.0.1 install: node-pre-gyp install --fallback-to-buil"?
This error occurs when bcrypt can't find prebuilt binaries and attempts to compile from source without necessary build tools. Install build dependencies or consider using bcryptjs as a pure JavaScript alternative.
What causes "npm ERR! bcrypt@5.0.1 install: node-pre-gyp install --fallback-to-buil"?
Build tools (gcc, g++, make) not installed Python not installed or not in PATH node-gyp not properly configured
Is the "npm ERR! bcrypt@5.0.1 install: node-pre-gyp install --fallback-to-buil" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading