Install & Compatibility
Where this runs
tested against v1.9.3 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.084s · 19.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.077s · 20MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CryptContext
✓ from passlib.context import CryptContext
✗ from libpass.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`.
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}")
Debug
Known issues
breakingThe `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.fixUpgrade `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.
affects: libpass < 1.9.3 when used with bcrypt >= 5.0.0
breakingPython 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.fixUpgrade `libpass` to version 1.8.0 or newer. This version adds Python 3.13 support by incorporating `legacycrypt` to provide the necessary functionality.
affects: libpass < 1.8.0 with Python 3.13+
gotchaInstalling 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.fixEnsure that only `libpass` is installed in your Python environment. Uninstall `passlib` before installing `libpass` if you are migrating from the original library.
affects: All versions when both packages are installed
gotchaWhile 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.fixAlways use `from passlib.<module> import <symbol>` for all imports related to this library.
affects: All versions of libpass
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'passlib'
The `libpass` package is not installed in the currently active Python environment, or the virtual environment is not correctly activated.
fixEnsure `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
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.
fixUpgrade `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'
You are attempting to import from `libpass.context` instead of `passlib.context`. `libpass` maintains the original `passlib` import paths for compatibility.
fixChange your import statement to `from passlib.context import CryptContext`.
Upgrade
Version history
1.9.3latest on PyPI · released Oct 9, 2025
Audit
Dependencies
bcryptoptionalOptional backend for bcrypt hashing schemes. Requires `pip install libpass[bcrypt]`.
argon2-cffioptionalOptional backend for Argon2 hashing schemes. Requires `pip install libpass[argon2]`.
legacycryptrequiredProvides the `crypt` module functionality for Python 3.13+ where it was removed. Included by default in libpass >= 1.8.0.