argon2-cffi

argon2-cffi is the standard Python library for hashing and verifying passwords with Argon2, the algorithm that won the Password Hashing Competition and is now widely recommended (including by OWASP) as the default choice for new applications. Its PasswordHasher class wraps the sensible-defaults complexity of Argon2’s memory cost, time cost, and parallelism parameters behind a two-method API: hash(password) and verify(hash, password).

Under the hood, the high-level API sits on top of low_level.py, which exposes the raw Argon2 primitives directly for advanced users, and on the separate argon2-cffi-bindings package (also maintained by the same author) for the actual CFFI/C bindings to the reference Argon2 implementation. The project also ships a check_needs_rehash() helper and a profiles module with pre-tuned parameter sets (RFC-recommended, low-memory, etc.) so applications can adopt secure defaults without tuning Argon2 parameters themselves.

What You Get

• PasswordHasher class with hash(), verify(), and check_needs_rehash() for full password lifecycle management
• Pre-tuned parameter profiles (e.g. RFC-9106 recommended, low-memory) so apps don’t have to hand-tune Argon2 cost parameters
• A low_level module exposing raw hash_secret/verify_secret primitives for advanced/custom use cases
• Typed exceptions (VerifyMismatchError, VerificationError, InvalidHash) for precise error handling in auth flows
• A __main__ CLI entry point for quick command-line hashing/benchmarking
• Binary wheels for major platforms via the companion argon2-cffi-bindings package, avoiding a local C toolchain requirement

Common Use Cases

• Hashing and verifying user passwords in a web application’s authentication system, replacing bcrypt/PBKDF2
• Upgrading legacy password hashes over time using check_needs_rehash() as cost parameters are tuned upward
• Choosing security/performance trade-offs via profiles presets instead of manually tuning memory/time cost
• Framework integration as the password hasher backend for Django, Flask-Security, or custom auth stacks
• Benchmarking or scripting Argon2 hashing operations directly from the command line via the bundled CLI

Under The Hood

Architecture — _password_hasher.py’s PasswordHasher class is a thin, opinionated layer over low_level.py, which itself calls into the separate argon2-cffi-bindings package’s CFFI bindings to the vendored C reference implementation of Argon2; _legacy.py preserves an older, pre-PasswordHasher API for backward compatibility, and profiles.py centralizes named parameter presets so callers don’t hardcode cost values. Tech Stack — Pure Python 3.9+ packaged with Hatchling/hatch-vcs, depending on the sibling argon2-cffi-bindings package for the actual C/CFFI layer — keeping this package itself free of a compiled build step while still shipping binary-wheel-backed performance. Code Quality — Test coverage is split cleanly by concern (test_password_hasher.py, test_low_level.py, test_legacy.py, test_utils.py, test_packaging.py), the project carries a CII Best Practices badge, and it enforces full type hints (py.typed marker) — a notably high bar for a security-critical dependency used across the Python ecosystem. API Design — PasswordHasher().hash(password) / .verify(hash, password) is the entire happy-path API surface, deliberately hiding Argon2’s five tunable cost parameters behind sane defaults and named profiles, which is precisely why it is the go-to library over hand-rolling low_level calls.