Install & Compatibility
Where this runs
tested against v1.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.010s · 23.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.3s · import 0.010s · 24MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Bcrypt
✓ from flask_bcrypt import Bcrypt
✗ from flask.ext.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.
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.")
Debug
Known issues
breakingEnabling 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.fixDecide 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.
affects: All versions
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.fixAlways 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. affects: Python 3.x
gotchaStoring 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.fixEnsure your database column for password hashes is long enough (e.g., `VARCHAR(255)` or `TEXT`) to accommodate the full bcrypt hash string.
affects: All versions
gotchaA `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.fixEnsure `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.
affects: All versions
gotchaWhen 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.fixExplicitly 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. affects: All versions, especially with PostgreSQL
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'flask_bcrypt'
The `flask-bcrypt` package is not installed in the current Python environment or the import statement is incorrect.
fixEnsure the package is installed using `pip install Flask-Bcrypt` (note the capital 'F' in the package name) and that the import statement is `from flask_bcrypt import Bcrypt`.
AttributeError: module 'bcrypt._bcrypt' has no attribute 'ffi'
This error typically occurs due to conflicting installations of `bcrypt` and `py-bcrypt`, or missing `cryptography` dependency, especially in deployment environments.
fixUninstall all related packages (`pip uninstall bcrypt py-bcrypt Flask-Bcrypt`), then reinstall `Flask-Bcrypt` along with `cryptography`: `pip install Flask-Bcrypt cryptography`.
ValueError: Invalid salt
This usually happens when `check_password_hash` or `generate_password_hash` receives an invalid hash string, often due to truncating the stored hash in the database (e.g., using a `VARCHAR` column that is too short) or attempting to check a plaintext password against a hash that wasn't properly generated/stored.
fixEnsure your database column for storing password hashes is large enough (e.g., `String(60)` for SQLAlchemy, or `TEXT`/`VARCHAR(255)` for raw SQL) to accommodate the full bcrypt hash string. Also, verify that the input to `check_password_hash` is an actual bcrypt hash and not a plaintext password, and that the password being hashed by `generate_password_hash` is not empty.
TypeError: Unicode-objects must be encoded before hashing
In Python 3, `bcrypt.generate_password_hash` expects a bytes-like object as input, but a Unicode string (str) is being passed without explicit encoding.
fixEncode the password string to bytes before passing it to `generate_password_hash`, for example: `bcrypt.generate_password_hash(password.encode('utf-8'))`. Note that `flask-bcrypt`'s `generate_password_hash` itself will return bytes, so you might also need to `.decode('utf-8')` the result if you intend to store it as a UTF-8 string in your database. Upgrade
Version history
1.0.1latest on PyPI · released Apr 5, 2022
Audit
Dependencies
FlaskrequiredCore web framework integration.
bcryptrequiredThe underlying cryptographic hashing library.
python-dev / python-developtionalPython development headers required by the 'bcrypt' C library on some Linux distributions.