pwdlib: Modern Password Hashing for Python

0.3.0 · active · verified Sat Apr 11

pwdlib is a modern password hashing library for Python, providing an easy-to-use wrapper to hash and verify passwords with secure algorithms like Argon2 and Bcrypt. It aims to be an alternative to `passlib`, which has seen reduced maintenance. The current version is 0.3.0, and it maintains an active development status, with updates released as needed.

Warnings

breaking Python 3.9 is no longer supported as of version 0.3.0. Users on Python 3.9 must upgrade their Python version to 3.10 or later.
Fix: Upgrade your Python environment to version 3.10 or higher.
breaking In version 0.2.0, the argument order for `PasswordHash.verify()` and `PasswordHash.verify_and_update()` methods was reversed. The password is now the *first* argument, and the hash is the *second* argument, for consistency with `passlib`'s API. [cite: original text]
Fix: Update calls to `verify(password, hash)` and `verify_and_update(password, hash)`. For example, `password_hash.verify(old_hash, 'password')` should become `password_hash.verify('password', old_hash)`.
gotcha `pwdlib` is not a direct, drop-in replacement for `passlib`. While inspired by `passlib`, it focuses on modern algorithms (Argon2, Bcrypt) and does not support many legacy hashing algorithms or advanced `CryptContext` features found in `passlib`.
Fix: Review `pwdlib`'s documentation for supported features and algorithms. If migrating from `passlib`, be aware of potential incompatibilities, especially with older hash formats or custom `CryptContext` configurations.
gotcha The `PasswordHash.recommended()` method currently defaults to Argon2. If you need to explicitly use Bcrypt or a different configuration of hashers, you must instantiate `PasswordHash` with a sequence of `HasherProtocol` objects.
Fix: To use custom hashers, import them (e.g., `from pwdlib.hashers.bcrypt import BcryptHasher`) and instantiate `PasswordHash` explicitly: `password_hash = PasswordHash((BcryptHasher(),))`.

Install

pip install 'pwdlib[argon2]' Recommended installation with Argon2 support
pip install 'pwdlib[bcrypt]' Installation with Bcrypt support
pip install pwdlib Minimal installation (no default hashers)

Imports

PasswordHash
```
from pwdlib import PasswordHash
```

Quickstart

This quickstart demonstrates how to initialize the recommended password hashing configuration, hash a plain-text password, and then verify it. It also shows the `verify_and_update` method for automatic hash upgrades.

from pwdlib import PasswordHash

# Get a PasswordHash instance with recommended hashers (currently Argon2)
password_hash = PasswordHash.recommended()

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

# Verify a password
is_valid = password_hash.verify("mysecretpassword", hashed_password)
print(f"Password is valid: {is_valid}")

# Verify and update (if hasher or hash needs upgrade)
is_valid_and_updated, new_hash = password_hash.verify_and_update("mysecretpassword", hashed_password)
print(f"Password valid and potentially updated: {is_valid_and_updated}, New hash: {new_hash}")

view raw JSON →