pwdlib

library0.3.1pypypi✓ verified 25d ago

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.

auth-security

pip install 'pwdlib[argon2]'

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · PWDLIB

pwdlib

auth-securitypythonv0.3.1

Install

1.7s avg

Import

12ms

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.3.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

musl

py 3.10–3.915 runs

installs and imports cleanly · install 0.0s · import 0.012s · 19.9MB

glibc

py 3.10–3.915 runs

installs and imports cleanly · install 1.7s · import 0.011s · 20MB

18MB installed

● package 18MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PasswordHash

✓ from pwdlib import PasswordHash

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}")

Debug

Known issues

breakingPython 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.

affects: >=0.3.0

breakingIn 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)`.

affects: >=0.2.0

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.

affects: all

gotchaThe `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(),))`.

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pwdlib'

The pwdlib library or its required components (like Argon2 or Bcrypt backends) are not installed or are not accessible in the current Python environment.

fix

Install pwdlib with the recommended hashing algorithm support, for example: `pip install 'pwdlib[argon2]'` or `pip install 'pwdlib[bcrypt]'`.

TypeError: PasswordHasher.hash() got an unexpected keyword argument 'salt'

This error occurs when an incompatible version of the `argon2-cffi` library is installed, specifically with `argon2-cffi` version 21.3.0.

fix

Upgrade your `argon2-cffi` dependency to a compatible version, such as 23.1.0 or newer: `pip install --upgrade argon2-cffi`.

pwdlib.exceptions.UnknownHashError

This exception is raised when the hash provided to `PasswordHash.verify()` is not recognized by any of the hashers configured in the `PasswordHash` instance. This can happen if the hash was generated by an unsupported algorithm or if the `PasswordHash` instance was initialized without the correct hashers.

fix

Ensure that the `PasswordHash` instance is configured to support the algorithm used to create the hash. Use `PasswordHash.recommended()` for common algorithms or explicitly pass a sequence of `HasherProtocol` objects: `from pwdlib.hashers.bcrypt import BcryptHasher; password_hash = PasswordHash((BcryptHasher(),))`.

AssertionError: If no hashers are specified.

The `PasswordHash` class requires at least one hasher to be specified during its initialization, but it was instantiated without any hashers.

fix

Initialize `PasswordHash` either by using the recommended configuration or by explicitly providing a sequence of hasher objects: `password_hash = PasswordHash.recommended()` or `from pwdlib.hashers.argon2 import Argon2Hasher; password_hash = PasswordHash((Argon2Hasher(),))`.

Upgrade

Version history

0.3.1latest on PyPI · released Aug 12, 2026

Audit

Dependencies

argon2-cffioptionalProvides Argon2 hashing algorithm support (used by 'argon2' extra and recommended hasher).

bcryptoptionalProvides Bcrypt hashing algorithm support (used by 'bcrypt' extra).

Agent activity

54 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/frankie567/pwdlib ↗

packagehttps://pypi.org/project/pwdlib/ ↗

docshttps://frankie567.github.io/pwdlib/ ↗