Repository files navigation

Acceptable password hashing for your software and your servers (but you shouldreally use argon2id or scrypt)

To install bcrypt, simply:

$pip install bcrypt

Note that bcrypt should build very easily on Linux provided you have a Ccompiler and a Rust compiler (the minimum supported Rust version is 1.56.0).

For Debian and Ubuntu, the following command will ensure that the required dependencies are installed:

$sudo apt-get install build-essential cargo

For Fedora and RHEL-derivatives, the following command will ensure that the required dependencies are installed:

$sudo yum install gcc cargo

For Alpine, the following command will ensure that the required dependencies are installed:

$apk add --update musl-dev gcc cargo

While bcrypt remains an acceptable choice for password storage, depending on your specific use case you may also want to consider using scrypt (either viastandard library orcryptography) or argon2id viaargon2_cffi.

• Dropped support for Python 3.7.
• We now support free-threaded Python 3.13.
• We now support PyPy 3.11.
• We now publish wheels for free-threaded Python 3.13, for PyPy 3.11 onmanylinux, and for ARMv7l onmanylinux.

• Bump Rust dependency versions - this should resolve crashes on Python 3.13free-threaded builds.
• We no longer buildmanylinux wheels for PyPy 3.9.

• Bump Rust dependency versions
• Removed theBCRYPT_ALLOW_RUST_163 environment variable.

• Bump Rust dependency versions

• Publish bothpy37 andpy39 wheels. This should resolve some errorsrelating to initializing a module multiple times per process.

• Fixed the type signature on thekdf method.
• Fixed packaging bug on Windows.
• Fixed incompatibility with passlib package detection assumptions.

• Dropped support for Python 3.6.
• Bumped MSRV to 1.64. (Note: Rust 1.63 can be used by setting theBCRYPT_ALLOW_RUST_163 environment variable)

• We now build PyPymanylinux wheels.
• Fixed a bug where passing an invalidsalt tocheckpw could result inapyo3_runtime.PanicException. It now correctly raises aValueError.

• bcrypt is now implemented in Rust. Users building from source will needto have a Rust compiler available. Nothing will change for users downloadingwheels.
• We no longer shipmanylinux2010 wheels. Users should upgrade to the latestpip to ensure this doesn’t cause issues downloading wheels on theirplatform. We now shipmanylinux_2_28 wheels for users on new enough platforms.
• NUL bytes are now allowed in inputs.

• Fixed packaging ofpy.typed files in wheels so thatmypy works.

• Added support for compilation on z/OS
• The next release ofbcrypt with be 4.0 and it will require Rust atcompile time, for users building from source. There will be no additionalrequirement for users who are installing from wheels. Users on mostplatforms will be able to obtain a wheel by making sure they have an up todatepip. The minimum supported Rust version will be 1.56.0.
• This will be the final release for which we shipmanylinux2010 wheels.Going forward the minimum supported manylinux ABI for our wheels will bemanylinux2014. The vast majority of users will continue to receivemanylinux wheels provided they have an up to datepip.

• Added typehints for library functions.
• Dropped support for Python versions less than 3.6 (2.7, 3.4, 3.5).
• Shippedabi3 Windows wheels (requires pip >= 20).

• Set asetuptools lower bound for PEP517 wheel building.
• We no longer distribute 32-bitmanylinux1 wheels. Continuing to producethem was a maintenance burden.

• Added support for compilation on Haiku.

• Added support for compilation on AIX.
• Dropped Python 2.6 and 3.3 support.
• Switched to usingabi3 wheels for Python 3. If you are not getting awheel on a compatible platform please upgrade yourpip version.

• Fixed compilation with mingw and on illumos.

• Fixed a compilation issue on Solaris.
• Added a warning when using too few rounds withkdf.

• Fixed a compile issue affecting big endian platforms.
• Fixed invalid escape sequence warnings on Python 3.6.
• Fixed building in non-UTF8 environments on Python 2.

• Resolved aUserWarning when used withcffi 1.8.3.

• Added support forcheckpw, a convenience method for verifying a password.
• Ensure that you get a$2y$ hash when you input a$2y$ salt.
• Fixed a regression where$2a hashes were vulnerable to a wraparound bug.
• Fixed compilation under Alpine Linux.

• Switched the C backend to code obtained from the OpenBSD project rather thanopenwall.
• Added support forbcrypt_pbkdf via thekdf function.

• Added support for an adjustible prefix when callinggensalt.
• Switched to CFFI 1.0+

Hashing and then later checking that a password matches the previous hashedpassword is very simple:

>>>import bcrypt>>> password=b"super secret password">>># Hash a password for the first time, with a randomly-generated salt>>> hashed= bcrypt.hashpw(password, bcrypt.gensalt())>>># Check that an unhashed password matches one that has previously been>>># hashed>>>if bcrypt.checkpw(password, hashed):...print("It Matches!")...else:...print("It Does not Match :(")

As of 3.0.0bcrypt now offers akdf function which doesbcrypt_pbkdf.This KDF is used in OpenSSH's newer encrypted private key format.

>>>import bcrypt>>> key= bcrypt.kdf(...     password=b'password',...     salt=b'salt',...     desired_key_bytes=32,...     rounds=100)

One of bcrypt's features is an adjustable logarithmic work factor. To adjustthe work factor merely pass the desired number of rounds tobcrypt.gensalt(rounds=12) which defaults to 12):

>>>import bcrypt>>> password=b"super secret password">>># Hash a password for the first time, with a certain number of rounds>>> hashed= bcrypt.hashpw(password, bcrypt.gensalt(14))>>># Check that a unhashed password matches one that has previously been>>>#   hashed>>>if bcrypt.checkpw(password, hashed):...print("It Matches!")...else:...print("It Does not Match :(")

Another one of bcrypt's features is an adjustable prefix to let you define whatlibraries you'll remain compatible with. To adjust this, pass either2a or2b (the default) tobcrypt.gensalt(prefix=b"2b") as a bytes object.

As of 3.0.0 the$2y$ prefix is still supported inhashpw but deprecated.

The bcrypt algorithm only handles passwords up to 72 characters, any charactersbeyond that are ignored. To work around this, a common approach is to hash apassword with a cryptographic hash (such assha256) and then base64encode it to prevent NULL byte problems before hashing the result withbcrypt:

>>> password=b"an incredibly long password"*10>>> hashed= bcrypt.hashpw(...     base64.b64encode(hashlib.sha256(password).digest()),...     bcrypt.gensalt()... )

This library should be compatible with py-bcrypt and it will run on Python3.8+ (including free-threaded builds), and PyPy 3.

bcrypt follows thesame security policy as cryptography, if youidentify a vulnerability, we ask you to contact us privately.