Flask-Bcrypt

Warnings

• breaking Enabling or disabling the `BCRYPT_HANDLE_LONG_PASSWORDS` configuration option on an existing project will break password checking for all users. This option changes how passwords longer than 72 bytes are handled.
  Fix: Decide on a strategy for long passwords (e.g., pre-hashing them with SHA256 before passing to bcrypt) before deployment and stick to it. Do not change this setting on a live project with existing user passwords.
• gotcha `generate_password_hash()` returns a byte string. In Python 3, this often needs to be explicitly decoded (e.g., using `.decode('utf-8')`) before storing in a database column that expects a Unicode string, or when passing it to `check_password_hash` if the stored hash is a string.
  Fix: Always append `.decode('utf-8')` to the output of `generate_password_hash()` if you intend to store or compare the hash as a standard string. Ensure your database column can store the full length of the decoded hash.
• gotcha Storing the hashed password in a database column with insufficient length (e.g., `VARCHAR(50)`) will truncate the hash, causing `check_password_hash` to consistently return `False` even for correct passwords.
  Fix: Ensure your database column for password hashes is long enough (e.g., `VARCHAR(255)` or `TEXT`) to accommodate the full bcrypt hash string.
• gotcha A `ModuleNotFoundError: No module named 'bcrypt'` error can occur if the underlying `bcrypt` library is not installed correctly or if Python development headers are missing on non-Windows systems during its installation.
  Fix: Ensure `pip install flask-bcrypt` completes without errors. On Linux, you might need to install `python-dev` (Debian/Ubuntu) or `python-devel` (RedHat/CentOS) packages first.
• gotcha When using `flask-bcrypt` with databases like PostgreSQL, you might encounter encoding-related `TypeError` issues if hashed passwords or plaintext passwords are not consistently handled as byte strings during comparison.
  Fix: Explicitly convert both the stored hashed password and the incoming plaintext password to byte strings (e.g., `bytes(stored_hash, 'utf-8')` and `password.encode('utf-8')`) before passing them to `check_password_hash` to ensure type consistency.

Install

• pip install flask-bcrypt Install with pip

Imports

• Bcrypt

  from flask_bcrypt import Bcrypt

  The `flask.ext` prefix for extensions is an outdated pattern from older Flask versions. Modern Flask extensions are imported directly from their package name.

Quickstart

This quickstart demonstrates how to initialize Flask-Bcrypt with your Flask application and use its primary methods, `generate_password_hash` and `check_password_hash`, to secure user passwords. Note the `.decode('utf-8')` call for Python 3 compatibility when storing the hash as a string.

from flask import Flask
from flask_bcrypt import Bcrypt

app = Flask(__name__)
# Configure secret key for session management, if applicable
app.config['SECRET_KEY'] = 'a_very_secret_key_for_demo'

bcrypt = Bcrypt(app)

# Example usage in a Flask context (e.g., a route or application setup)
password_plaintext = "mysecretpassword123"

# Generate a password hash (output is bytes, must decode for storage/comparison as string in Py3)
pw_hash = bcrypt.generate_password_hash(password_plaintext).decode('utf-8')

print(f"Plaintext Password: {password_plaintext}")
print(f"Hashed Password: {pw_hash}")

# Check a password against the hash
is_correct = bcrypt.check_password_hash(pw_hash, password_plaintext)
print(f"Password check against correct password: {is_correct}") # Should be True

is_wrong = bcrypt.check_password_hash(pw_hash, "wrongpassword")
print(f"Password check against wrong password: {is_wrong}") # Should be False

if __name__ == '__main__':
    # In a real app, you would store pw_hash in a database
    # and then retrieve it for check_password_hash
    # For demonstration, we just print the results.
    print("Quickstart demonstrated hashing and checking.")