Fix Cannot Find Module 'bcrypt' Error

Encountering the error "Cannot find module 'bcrypt'" in Node.js can be frustrating, especially for beginners. This error usually appears when you try to import or require bcrypt in your project, but Node.js cannot locate the module. It often happens after cloning a repository, updating dependencies, or switching Node versions. In this guide, we will walk through the most common causes and simple solutions to fix this error quickly.

First, let's understand why this error occurs. The bcrypt library is a popular npm package used for hashing passwords securely. It relies on native C++ code that must be compiled during installation. If the installation fails or the module is missing from your node_modules folder, Node.js throws the "Cannot find module" error. The good news is that fixing it is usually straightforward.

1. Reinstall bcrypt from Scratch

The most common fix is to reinstall bcrypt. Start by removing the existing module and its dependencies. Then, install it again using npm. This ensures you get the correct version for your Node.js environment.

# Remove bcrypt from node_modules
npm uninstall bcrypt

# Clear npm cache (optional but helpful)
npm cache clean --force

# Install bcrypt fresh
npm install bcrypt

After running these commands, try running your application again. This often resolves the issue because the reinstallation compiles the native code correctly for your current system.

If you still see the error, check your package.json file to ensure bcrypt is listed under dependencies. You can also verify the installation by checking the node_modules/bcrypt folder exists.

2. Check Node.js and npm Versions

Sometimes the error occurs because your Node.js version is incompatible with the bcrypt version. bcrypt requires a recent Node.js version (typically Node.js 14 or higher). Use the node -v command to check your version. If it's outdated, update Node.js.

# Check your current Node.js version
node -v

# Check npm version
npm -v

If you are using an older version like Node.js 12, consider upgrading to Node.js 18 or 20. You can use a version manager like nvm (Node Version Manager) to switch between versions easily.

After updating Node.js, remove the node_modules folder and package-lock.json file, then run npm install again. This ensures all dependencies are rebuilt for the new Node.js version.

3. Use bcryptjs as an Alternative

If you continue to face issues with the native bcrypt module, consider using bcryptjs. This is a pure JavaScript implementation that does not require native compilation. It works consistently across all platforms and Node.js versions. While it is slightly slower than the native version, it is reliable for most applications.

# Uninstall bcrypt first
npm uninstall bcrypt

# Install bcryptjs
npm install bcryptjs

After installing bcryptjs, update your require or import statements in your code to use bcryptjs instead of bcrypt. The API is identical, so you only need to change the module name.

// Before (causes error)
const bcrypt = require('bcrypt');

// After (works with bcryptjs)
const bcrypt = require('bcryptjs');

// Now you can use the same functions
const hash = await bcrypt.hash('password123', 10);
console.log(hash); // Output: $2a$10$...

This simple swap often fixes the "Cannot find module" error permanently without needing to troubleshoot native compilation issues.

4. Ensure Proper Import Syntax

Another common cause is using the wrong import syntax. If you are using ES modules (with import instead of require), make sure your package.json has "type": "module" or use the correct file extension (e.g., .mjs). Mixing CommonJS and ES modules can lead to module resolution errors.

// For CommonJS (default)
const bcrypt = require('bcrypt');

// For ES modules (if "type": "module" is set)
import bcrypt from 'bcrypt';

If you see an error like "require is not defined", you are likely using ES modules but trying to use CommonJS syntax. Stick to one style consistently. For beginners, we recommend using CommonJS (require) until you are comfortable with ES modules.

5. Check for Missing Build Tools

The native bcrypt module requires build tools like node-gyp and Python to compile. On Windows, you may need to install Visual Studio Build Tools or the Windows SDK. On macOS, Xcode Command Line Tools are required. On Linux, you need gcc and make.

# On macOS, install Xcode Command Line Tools
xcode-select --install

# On Ubuntu/Debian Linux, install build essentials
sudo apt-get install build-essential python3

# On Windows, install windows-build-tools (run as admin)
npm install --global windows-build-tools

After installing the required tools, delete the node_modules folder and run npm install again. This allows bcrypt to compile successfully.

If you still have problems with native builds, switching to bcryptjs as mentioned earlier is the simplest workaround.

6. Verify the Module Path

Sometimes the error occurs because your file is in a subfolder and cannot find the module. Node.js looks for modules in the node_modules folder of the current directory and its parent directories. Ensure your project has a node_modules folder in the root or a parent directory.

# Check if node_modules exists
ls node_modules/bcrypt

# If not, install dependencies
npm install

If you are working in a monorepo or using workspaces, make sure you run npm install from the correct directory. The module must be installed in the same project where you are running your code.

For more troubleshooting, read our detailed guide on Fix Node.js Error: Cannot find module which covers general module resolution issues.

Conclusion

The "Cannot find module 'bcrypt'" error in Node.js is common but easy to fix. Start by reinstalling the module and checking your Node.js version. If problems persist, switch to bcryptjs as a reliable alternative. Always ensure your import syntax matches your module system and that build tools are installed for native modules. By following these steps, you can quickly resolve the error and get back to building your application. Remember to keep your dependencies updated and your environment consistent to avoid similar issues in the future.