Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python bcrypt Password Hashing and Verification

Learn how to hash and verify passwords with Python bcrypt, including byte encoding, salts, cost factors, and common pitfalls.

~5 min readPython
#bcrypt#password hashing#authentication#Python security
A padlock and a Python code snippet illustrating bcrypt password hashing and verification.

When you store passwords in a Python application, the goal is not to encrypt them but to hash them with a one-way function that resists brute-force and rainbow-table attacks. The bcrypt library provides a straightforward API for generating and checking password hashes, but its behavior around byte encoding and the cost factor can trip up developers. This article walks through the practical steps of hashing and verifying passwords with bcrypt in Python, including the details that matter in production.

Why bcrypt for Password Hashing in Python

bcrypt is a password-hashing function based on the Blowfish cipher. It was designed to be computationally expensive, which makes brute-force attacks slower, and it automatically incorporates a random salt, which defeats precomputed rainbow tables. Unlike general-purpose cryptographic hashes like SHA-256, bcrypt is intentionally slow, making it a better fit for password storage.

The Python bcrypt package wraps the reference implementation and exposes a small set of functions. You do not need to manage salt generation or hash format parsing manually; the library handles both.

Installing the bcrypt Library

The bcrypt package is available on PyPI and can be installed with pip:

bash
pip install bcrypt

Once installed, import it in your Python code:

python
import bcrypt

The library is a C extension with a Python fallback, so it works on most platforms. For production, pin the version you use to avoid unexpected changes.

Hashing a Password with bcrypt

Hashing a password with bcrypt requires two steps: generate a salt and then hash the password with that salt. The gensalt function creates a random salt and encodes the cost factor into it. The hashpw function combines the password bytes and the salt to produce the final hash.

python
import bcrypt password = b"correct horse battery staple" salt = bcrypt.gensalt() hashed = bcrypt.hashpw(password, salt)

The hashed value is a byte string that contains the salt, the cost factor, and the actual hash. It is safe to store this value directly in a database column. The salt is embedded in the hash, so you do not need to store it separately.

You can also pass a rounds argument to gensalt to set the cost factor explicitly:

python
salt = bcrypt.gensalt(rounds=12)

The default is 12, which is a reasonable starting point for most applications.

Verifying a Password with bcrypt

To verify a password, use checkpw. It takes the plaintext password bytes and the stored hash, and returns True if the password matches, False otherwise.

python
import bcrypt stored_hash = b"$2b$12$..." # from your database password = b"correct horse battery staple" if bcrypt.checkpw(password, stored_hash): print("Login successful") else: print("Invalid password")

The checkpw function extracts the salt and cost factor from the stored hash and recomputes the hash of the provided password. It is designed to compare hashes in constant time, which helps mitigate timing attacks.

How bcrypt Salt and Cost Factor Work

The salt is a random 16-byte value that ensures the same password produces different hashes each time it is hashed. This prevents attackers from using precomputed tables and makes it impossible to tell if two users have the same password just by comparing hashes.

The cost factor, often called rounds, controls how much work bcrypt does. It is stored as a two-digit number in the hash string, after the $2b$ prefix. For example, in $2b$12$..., the cost factor is 12. Each increment doubles the work required, so a cost of 13 is twice as slow as 12.

When you call gensalt, you specify the cost factor. The resulting salt string includes that value. When you call hashpw, the cost factor from the salt is used. When you call checkpw, the cost factor from the stored hash is used, so you can increase the cost factor over time without breaking existing hashes.

Handling Bytes and Encoding Correctly

bcrypt operates on bytes, not strings. If your password is a Python str, you must encode it to bytes before passing it to hashpw or checkpw. The most common encoding is UTF-8:

python
password = "correct horse battery staple" password_bytes = password.encode("utf-8") hashed = bcrypt.hashpw(password_bytes, bcrypt.gensalt())

Be consistent with the encoding. If you encode with UTF-8 during hashing, you must encode with UTF-8 during verification. Using different encodings will produce different byte sequences and cause verification to fail.

Another critical detail is that bcrypt is defined for passwords up to 72 bytes. Depending on the library version, longer input may be truncated or rejected. Do not rely on bytes beyond the first 72 bytes. If your application allows longer passwords, decide on a policy: enforce a maximum, truncate explicitly, or pre-hash the password with a separate algorithm before passing it to bcrypt. Whichever approach you choose, apply it consistently during hashing and verification.

Common bcrypt Mistakes and Edge Cases

One frequent mistake is passing a str directly to hashpw or checkpw. This raises a TypeError because bcrypt expects bytes. Always encode your password strings.

Another issue is storing the hash as a str instead of bytes. When you read it back from a database, you may get a string. You need to encode it to bytes before calling checkpw. For example:

python
stored_hash_str = "$2b$12$..." # from a text column stored_hash = stored_hash_str.encode("utf-8")

If you store the hash in a bytes column, you avoid this conversion.

A third mistake is reusing the same salt for multiple passwords. This defeats the purpose of salt. Always call gensalt for each password you hash.

Finally, do not try to implement your own password verification logic by comparing hashes. Use checkpw; it handles the parsing and timing aspects correctly.

Setting the Cost Factor for Production

The cost factor is a tradeoff between security and performance. A higher cost factor makes brute-force attacks more expensive but also increases the CPU time required for every login and registration. You need to choose a value that is high enough to be secure but low enough to keep your authentication endpoints responsive.

A common approach is to benchmark gensalt and hashpw on your production hardware and pick the highest cost factor that still meets your latency budget. The default of 12 is a reasonable baseline, but you should adjust it based on your environment.

Because the cost factor is embedded in the hash, you can increase it over time. When a user logs in, you can check if their hash uses an older, lower cost factor and re-hash the password with the new setting. This allows you to strengthen security without forcing users to reset their passwords.

bcrypt hashes include a prefix that indicates the bcrypt version, such as $2a$ or $2b$. The $2b$ prefix is the current standard and is what gensalt produces by default. If you have legacy hashes with a different prefix, confirm that your bcrypt version accepts that prefix before relying on it.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.