Skip to content

# pwdlib

Modern password hashing for Python

- Build status
- Test coverage
- PyPI
- Downloads
- Support development

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 uv to manage the development environment and production build, and just to manage command shortcuts. Ensure they are installed on your system.

### Run unit tests

You can run all the tests with:

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