How to Install bcrypt with npm i bcrypt in Node.js: Complete Guide

Run npm i bcrypt to install the bcrypt password-hashing library; because it contains native C++ bindings, npm will trigger node-gyp to compile the module, requiring Python and a C++ compiler to be installed on your system.

bcrypt is a widely-used library for hashing passwords in Node.js applications using the Blowfish cipher. When you execute the npm i bcrypt command, npm downloads the package from the registry and compiles native bindings using the bundled node-gyp tool. This article provides the exact installation steps, usage examples, and a technical deep dive into how Node.js loads these native addons.

The npm i bcrypt Installation Process

Execute the installation command in your project root:

npm i bcrypt

When you run this command, npm performs three critical operations:

1. Resolution and download: npm queries the registry for the bcrypt package and downloads the source tarball to node_modules/bcrypt/.
2. Native compilation trigger: The package's package.json contains "gypfile": true, signaling npm to invoke node-gyp (located in deps/npm/node_modules/node-gyp/ within the Node.js source).
3. Binary generation: node-gyp reads the binding.gyp file, generates platform-specific build files (Makefile or Visual Studio project), and compiles bcrypt_lib.cc into a .node shared library.

The compiled binary lands in node_modules/bcrypt/lib/binding/<platform>-<arch>/bcrypt_lib.node. Node.js loads this file at runtime using the internal module loader implemented in src/node_module.cc.

Prerequisites for Compiling Native Addons

Because bcrypt is a native addon, npm i bcrypt requires specific system tools to compile C++ code. According to the Node.js build system, you need:

• Python 2.7 or 3.x: Used by gyp to generate build files. On Windows, the tools/msvs/install_tools.bat script can help install the necessary components.
• C/C++ compiler: On Unix systems, GCC or Clang; on Windows, the Visual Studio Build Tools (detected via vcbuild.bat).
• node-gyp: Bundled with Node.js's npm at deps/npm/node_modules/node-gyp/, this tool orchestrates the compilation.

If any prerequisite is missing, the installation aborts with errors like "unable to find python executable" or "MSBuild not found". Install these tools once to enable all future native module builds.

Using bcrypt in Your Application

After npm i bcrypt completes successfully, require the module and hash passwords using either the asynchronous (recommended) or synchronous API.

Asynchronous approach (non-blocking, preferred for servers):

const bcrypt = require('bcrypt');

// Generate salt with 10 rounds (default cost factor)
bcrypt.genSalt(10, (err, salt) => {
  if (err) throw err;
  
  const password = 'my-Secret123!';
  
  // Hash the password
  bcrypt.hash(password, salt, (err, hash) => {
    if (err) throw err;
    console.log('Hash:', hash);
    
    // Verify password
    bcrypt.compare(password, hash, (err, match) => {
      if (err) throw err;
      console.log('Password matches?', match); // true
    });
  });
});

Synchronous approach (blocking, acceptable for scripts):

const bcrypt = require('bcrypt');

const salt = bcrypt.genSaltSync(12); // Higher rounds = more secure but slower
const hash = bcrypt.hashSync('my-Secret123!', salt);
const isValid = bcrypt.compareSync('my-Secret123!', hash);

console.log({ hash, isValid });

The async version prevents event-loop blocking during the computationally expensive hashing operation.

How Node.js Supports Native Addons

The ability to require('bcrypt') and execute C++ code relies on Node.js's addon infrastructure. When npm i bcrypt compiles the module, it produces a .node file that Node.js loads through specific mechanisms:

• Addon loading: The node::Load function in src/node_module.cc exposes the process.dlopen binding that maps the compiled binary into memory.
• JavaScript bridge: src/js_native_api.cc implements N-API, providing a stable interface for C++ functions to be called from JavaScript.
• Event-loop integration: Asynchronous bcrypt operations use src/threadpoolwork-inl.h and src/uv.cc to schedule work on libuv's thread pool, preventing blocking.
• Build system: The tools/gyp/ directory contains Node.js's fork of the gyp build generator, which node-gyp invokes to create platform-specific build files from binding.gyp.

When your code calls bcrypt.hash(), execution flows from JavaScript through the N-API layer in src/js_native_api.cc, into the compiled C++ Blowfish implementation, with async work managed by the libuv thread pool defined in src/uv.cc.

Troubleshooting npm i bcrypt Failures

If npm i bcrypt errors, match the symptom to the solution:

• gyp ERR! find Python: Install Python 2.7 or 3.x and ensure it is in your system PATH.
• gcc: command not found (Linux/macOS): Install build tools via sudo apt-get install build-essential (Debian/Ubuntu) or xcode-select --install (macOS).
• MSBUILD : error MSB3428 (Windows): Install Visual Studio Build Tools and run vcbuild.bat or use the Windows tools installer script at tools/msvs/install_tools.bat.
• bcrypt_lib.node not found: The build failed silently. Run npm rebuild bcrypt --build-from-source to see detailed compiler output.

Summary

• Install bcrypt using npm i bcrypt, which triggers a native compilation step via node-gyp.
• Prerequisites include Python, a C++ compiler, and on Windows, Visual Studio Build Tools; these are required because the module uses native bindings.
• Implementation relies on Node.js's addon architecture in src/node_module.cc, src/js_native_api.cc, and src/uv.cc to bridge JavaScript and C++.
• API choice: Use the asynchronous genSalt, hash, and compare methods in production to avoid blocking the event loop.
• Compiled output is stored in node_modules/bcrypt/lib/binding/ as a platform-specific .node binary loaded at runtime.

Frequently Asked Questions

Why does npm i bcrypt fail with "gyp ERR! find Python"?

node-gyp, which is bundled with Node.js at deps/npm/node_modules/node-gyp/, requires Python to generate platform-specific build files from the binding.gyp configuration. Install Python 2.7 or 3.x and ensure the executable is in your system PATH, or set the PYTHON environment variable to the binary location.

What is the difference between bcrypt.genSalt and bcrypt.genSaltSync?

bcrypt.genSalt is asynchronous and accepts a callback, allowing the event loop to process other operations while generating the salt. bcrypt.genSaltSync blocks execution until the salt is generated. For production web servers, always use the asynchronous API to maintain responsiveness.

Where does Node.js store the compiled bcrypt binary after npm i bcrypt runs?

After successful compilation, node-gyp places the binary at node_modules/bcrypt/lib/binding/<platform>-<arch>/bcrypt_lib.node. Node.js loads this file via process.dlopen, implemented in src/node_module.cc, when you execute require('bcrypt').

Can I use bcrypt without installing compilation tools?

If you cannot install Python or a C++ compiler, use bcryptjs, a pure JavaScript implementation with the same API. However, it is significantly slower than the native bcrypt module compiled by npm i bcrypt because it lacks the optimized C++ Blowfish implementation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}