Installation Instructions

bcrypt is a native module for NodeJS, i.e, it uses native code to perform its work. The advantage of this over pure JS alternatives is speed. However, the disadvantage of this approach is it requires you to install a compiler and build dependencies in order to build.

We try to offer pre-built libraries for some platforms, but they are not always readily available since we developers do not own machines in all the architectures NodeJS is available for. Pre-compiled libraries for Windows, Linux and MacOS should be available and installed automatically by node-pre-gyp while installing bcrypt.

However, if the pre-compiled libraries are not yet available, or if you are willing to contribute to this library, you need to follow the instructions on this page.

Note: If precompiled binaries are not available, you will see an error like this:

node-pre-gyp ERR! Tried to download(404): https://github.com/kelektiv/node.bcrypt.js/releases/download/v1.0.2/bcrypt_lib-v1.0.2-node-v48-linux-x64.tar.gz

This is not an error, npm install just falls back to compile from source, so it requires you to install a compiler. It is this part most users are facing errors. Make sure you have Python 2, a C++ compiler, and a make system installed.

The instructions in this page are not exhaustive and do not cover all platforms and distributions. If you get bcrypt installed on a platform not listed here, please edit this page and add your steps.

1. Linux
   1. Ubuntu and derivatives (Linux Mint, Elementary OS etc.)
   2. Fedora
   3. RHEL and derivatives (CentOS, Amazon Linux, Oracle Linux etc.)
2. Microsoft Windows
3. Docker

Linux

Linux machines come with a large variety of flavors and distributions. We only have instructions for the most commonly used distributions. However, you are welcome to contribute instructions for your distribution.

Note: In all cases, NodeJS 6.x and 7.x were installed from NodeSource repositories.

Opensuse

Tested on:

• openSUSE-Tumbleweed-JeOS.x86_64-15.1.0

• g++ - In order to install a compiler chain to compile the node modules.
• make - Part of compiler toolchain.

This one liner should make sure all required packages are installed:

sudo zypper install gcc-c++ make

Ubuntu (and derivatives - Elementary, Linux Mint etc.)

Tested on:

• Ubuntu 16.04.2 "Xenial Xerus" x64 (fresh install on AWS, Digital Ocean, Ubuntu Server ISO, Ubuntu desktop)
• Elementary OS 0.4 "Loki" x64 (based on Ubuntu 16.04.1)

• g++ - In order to install a compiler chain to compile the node modules.
• make - Part of compiler toolchain.
• python (for server images, desktop images come with python installed) - 16.04 server defaults to python 3 so does not come with python 2. However, node-gyp requires python 2 to be installed.

This one liner should make sure all required packages are installed:

sudo apt-get install -y build-essential python

Fedora

Tested on:

• Fedora 25 Workstation x64 (booted from Live CD, equivalent to fresh install)
• Fedora 25 Server x64 (fresh install on DigitalOcean)

• gcc-c++ - In order to install a compiler chain to compile the node modules.
• make - To run the generated Makefile by node-gyp, which invokes compilers in order
• python - Fedora Workstation come with the required version of python installed. In Fedora server, installing NodeJS also installs the required version of python

dnf install gcc-c++ make

RHEL and CentOS

Tested on:

• CentOS 6.8
• CentOS 7.3
• RHEL 7.2

Derivatives like Amazon Linux and Oracle Linux should also work with these instructions as they mirror RHEL very closely. There have been reports of Amazon Linux working.

• gcc-c++ - In order to install a compiler chain to compile the node modules.
• make - To run the generated Makefile by node-gyp, which invokes compilers in order
• python - RHEL and CentOS come with the required version of python installed

Make sure all dependencies are installed with this command, and then proceed with bcrypt installation

yum install -y gcc-c++ make

Microsoft Windows

Tested on:

• Windows 7 64Bit Professional (Service Pack 1)
• Windows 10 64Bit Professional (Version 1607)

Open powershell with administrator privileges and run this command, then proceed with bcrypt installation

npm install --global --production windows-build-tools

Docker

Note: Only tested against official NodeJS images except the alpine variant. Instructions will be different for any other image.

Tested on:

• node:7.8
• node:6.10

Official Docker images (except the alpine version) for NodeJS contain all build dependencies, you need not to do anything special.

Alpine Linux based images

From version 4.0.1 we have started to provide pre-build library for musl libc and following recompiling step would be unnecessary. However, it's still experimental release and you may want to have recompiling step to make sure it works for your environment.

You need the following packages:

• build-base
• python

apk --no-cache add --virtual builds-deps build-base python

We recommend using no-cache and virtual, in order to keep the resulting container size same.

Alpine linux based images use musl libc instead of the standard glibc and thus are not compatible with compiled binaries. node-pre-gyp currently does not test the pre-compiled binaries to be ABI-compatible and thus you may see segfaults. We are working to resolve this issue.

As a workaround, In alpine based images, force recompiling the bcrypt native addon after a npm install with this command: npm rebuild bcrypt --build-from-source.

AWS Elastic Beanstalk

When deploying to Elastic Beanstalk running Node 8.x, node-gyp doesn't have sufficient permissions to write to the tmp directory. bcrypt won't install and the application deployment will fail.

A workaround is to add a .npmrc file to the root of your project that will force node-gyp to run as root and allow the installation to complete. File contents for .npmrc:

# Force npm to run node-gyp also as root, preventing permission denied errors in AWS with npm@5 or @6
unsafe-perm=true

Credit to this Stack Overflow post for the suggested solution.