libpass: Comprehensive Password Hashing Framework

Common errors

• ModuleNotFoundError: No module named 'passlib'

  cause The `libpass` package is not installed in the currently active Python environment, or the virtual environment is not correctly activated.
  fix Ensure `libpass` is installed via `pip install libpass`. Verify your virtual environment is activated, or that the correct Python interpreter is being used.

• ValueError: password cannot be longer than 72 bytes, truncate manually if necessary

  cause You are using `bcrypt` version 5.0.0 or higher with a password exceeding 72 bytes. `bcrypt` 5.0.0 changed its behavior to raise an error for overly long passwords, instead of silently truncating them.
  fix Upgrade `libpass` to version 1.9.3 or newer, as it includes compatibility fixes for `bcrypt` 5.0.0+. Alternatively, ensure that any passwords passed to `bcrypt` are 72 bytes or shorter, or pin `bcrypt<5.0.0` in your `requirements.txt`.

• ImportError: cannot import name 'CryptContext' from 'libpass.context'

  cause You are attempting to import from `libpass.context` instead of `passlib.context`. `libpass` maintains the original `passlib` import paths for compatibility.
  fix Change your import statement to `from passlib.context import CryptContext`.

Warnings

• breaking The `bcrypt` library (a common optional dependency) introduced a breaking change in version 5.0.0. Passwords longer than 72 bytes now raise a `ValueError` instead of being silently truncated. This can cause applications to fail if not handled.
  Fix: Upgrade `libpass` to version 1.9.3 or newer, which includes improved fixup for `bcrypt` >= 5.0.0. Alternatively, explicitly pin `bcrypt < 5.0.0` in your project's dependencies if upgrading `libpass` is not immediately possible. Ensure passwords are truncated before being passed to `bcrypt` if they exceed 72 bytes.
• breaking Python 3.13 removed the built-in `crypt` module, which older versions of `passlib` (and thus `libpass`) sometimes relied upon as a fallback. Running older `libpass` versions on Python 3.13+ can lead to `ModuleNotFoundError` or similar issues for certain hashing schemes.
  Fix: Upgrade `libpass` to version 1.8.0 or newer. This version adds Python 3.13 support by incorporating `legacycrypt` to provide the necessary functionality.
• gotcha Installing both the original `passlib` package and `libpass` concurrently can lead to unexpected behavior and import conflicts, as `libpass` is designed as a direct drop-in replacement.
  Fix: Ensure that only `libpass` is installed in your Python environment. Uninstall `passlib` before installing `libpass` if you are migrating from the original library.
• gotcha While the package is installed as `libpass`, all imports within your code should use `passlib` (e.g., `from passlib.context import CryptContext`). Attempting to import from `libpass` directly will result in an `ImportError` for this specific fork.
  Fix: Always use `from passlib.<module> import <symbol>` for all imports related to this library.

Install

• pip install libpass Install latest version

Imports

• CryptContext
  wrong:

  from libpass.context import CryptContext

  correct:

  from passlib.context import CryptContext

  Despite the package name being `libpass`, it is a drop-in replacement for `passlib` and uses the original `passlib` import paths. Importing from `libpass.context` is for the separate `libpass-next` project.
• pbkdf2_sha256

  from passlib.hash import pbkdf2_sha256

  Individual hashers are imported directly from `passlib.hash`.

Quickstart

This quickstart demonstrates how to use `passlib.context.CryptContext` to hash and verify passwords using multiple schemes. It showcases how to configure the context and perform basic hashing and verification operations.

from passlib.context import CryptContext

# Configure a context with desired hashing schemes
# Common schemes include 'sha512_crypt', 'bcrypt', 'pbkdf2_sha256', 'argon2'
context = CryptContext(
    schemes=["sha512_crypt", "bcrypt", "pbkdf2_sha256", "argon2"],
    # For real applications, configure rounds/iterations for security and performance
    sha512_crypt__rounds=656000,
    bcrypt__rounds=12,
    pbkdf2_sha256__rounds=150000
)

password = "supersecretpassword"

# Hash a password
hashed_password = context.hash(password)
print(f"Hashed password: {hashed_password}")

# Verify a password against a hash
is_valid = context.verify(password, hashed_password)
print(f"Password valid: {is_valid}")

# Example with a wrong password
is_invalid = context.verify("wrongpassword", hashed_password)
print(f"Wrong password valid: {is_invalid}")