/pwdlib

Modern password hashing for Python

Primary LanguagePythonMIT LicenseMIT

pwdlib

Modern password hashing for Python

build codecov PyPI version Downloads

Subscribe


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

We use Hatch to manage the development environment and production build. Ensure it's installed on your system.

Run unit tests

You can run all the tests with:

hatch run test

Format the code

Execute the following command to apply linting and check typing:

hatch run lint

Publish a new version

You can bump the version, create a commit and associated tag with one command:

hatch version patch
hatch version minor
hatch version major

Your default Git text editor will open so you can add information about the release.

When you push the tag on GitHub, the workflow will automatically publish it on PyPi and a GitHub release will be created as draft.

Serve the documentation

You can serve the Mkdocs documentation with:

hatch run docs-serve

It'll automatically watch for changes in your code.

License

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