pwdlib

Modern password hashing for Python

Documentation: https://frankie567.github.io/pwdlib/

Source Code: https://github.com/frankie567/pwdlib

Quickstart

pip install 'pwdlib[argon2]'

from pwdlib import PasswordHash

password_hash = PasswordHash.recommended()
hash = password_hash.hash("herminetincture")
password_hash.verify("herminetincture", hash)  # True

Why pwdlib?

For years, the de-facto standard to hash passwords was passlib. Unfortunately, it has not been very active recently and its maintenance status is under question. Starting Python 3.13, passlib won't work anymore.

That's why I decided to start pwdlib, a password hash helper for the modern Python era. However, it's not designed to be a complete replacement for passlib, which supports numerous hashing algorithms and features.

✅ Goals

• Provide an easy-to-use wrapper to hash and verify passwords
• Support modern and secure algorithms like Argon2 or Bcrypt

❌ Non-goals

• Support legacy hashing algorithms like MD5
• Implement algorithms directly — we should only rely on existing and battle-tested implementations

Development

Setup environment

Install uv and just. Use Python 3.11 or newer for Zensical and pre-commit.

Install the development dependencies and pre-commit hooks with just install.

Run unit tests

just test

Format the code

Run Ruff to format and lint the code, then check types with ty.

just lint

Use just lint-check to run the same checks without editing files.

Publishing a release

1. Commit the release notes under Unreleased in CHANGELOG.md. From a clean release branch with Git signing configured, run just version patch, just version minor, or just version major. The recipe updates the version, changelog, and lockfile, then opens your Git editor for the signed commit.
2. Preview the release notes with just release-notes <version>, then push the branch and merge the release PR into main.
3. With the GitHub CLI authenticated, run just release <PR number>. This signs and pushes a tag pointing to the merged PR commit. After the checks pass, CI publishes the distributions to PyPI with attestations and publishes the GitHub release with build provenance.

The PyPI Trusted Publisher must match the build.yml workflow and the GitHub release environment.

Serve the documentation

The documentation uses Zensical. Start the local preview with the following command.

just docs-serve

Open http://localhost:8000. The preview reloads when documentation changes. Edit pages in docs/ and configure the site in zensical.toml.

Build the static site into site/ with the following command.

just docs-build

License

This project is licensed under the terms of the MIT license.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Hynek Schlawack 💻

Waket Zheng 💻

This project follows the all-contributors specification. Contributions of any kind welcome!