argon2-cffi

library25.1.0pypypi✓ verified 25d ago

argon2-cffi is a Python library that provides secure password hashing using the Argon2 algorithm, the winner of the Password Hashing Competition. It offers a high-level API for hashing and verification, along with options to tune security parameters. The library is actively maintained and releases new versions with performance improvements, enhanced platform support, and updated RFC compliance.

auth-security serialization

pip install argon2-cffi

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · ARGON2-CFFI

argon2-cffi

auth-securitypythonv25.1.0

Install

2.2s avg

Import

48ms

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 v25.1.0 · 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.95 runs

installs and imports cleanly · install 0.0s · import 0.050s · 19.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.2s · import 0.046s · 20MB

18MB installed

● package 18MB

Code

Verified usage

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

PasswordHasher

✓ from argon2 import PasswordHasher

This is the primary class for hashing and verifying passwords.

VerifyMismatchError

✓ from argon2.exceptions import VerifyMismatchError

✗ except Exception as e:

When verifying a password, `VerifyMismatchError` is raised if the password does not match the hash. Catching this specific exception is best practice rather than a generic `Exception`.

This quickstart demonstrates how to initialize `PasswordHasher`, hash a password, verify it, and check if the hash needs to be updated due to changed parameters. Always catch `VerifyMismatchError` for password mismatches.

from argon2 import PasswordHasher from argon2.exceptions import VerifyMismatchError ph = PasswordHasher() # Hash a password password = "correct horse battery staple" hashed_password = ph.hash(password) print(f"Hashed: {hashed_password}") # Verify a password try: ph.verify(hashed_password, password) print("Verification successful!") except VerifyMismatchError: print("Verification failed: Password does not match.") except Exception as e: print(f"An unexpected error occurred during verification: {e}") # Check if a rehash is needed (e.g., if parameters changed) if ph.check_needs_rehash(hashed_password): print("Password needs re-hashing with new parameters.") else: print("Password hash parameters are up-to-date.")

Debug

Known issues

breakingPython 2.7, 3.4, 3.5, and 3.7 are no longer supported. The minimum Python version is now 3.8.

fix

Upgrade to Python 3.8 or newer. Ensure your project's `requires_python` matches.

affects: <=25.0.0 (specific removals: 2.7 in 21.1.0, 3.5 in 21.2.0, 3.7 in 25.1.0)

breakingThe legacy top-level functions `argon2.hash_password()`, `argon2.hash_password_raw()`, and `argon2.verify_password()` that were soft-deprecated since 2016 and hard-deprecated (raising `DeprecationWarning`) in 23.1.0 are now removed.

fix

Migrate to using the `argon2.PasswordHasher` class for all hashing and verification operations. For low-level APIs, use `argon2.low_level.hash_secret()` and `argon2.low_level.verify_secret()`.

affects: >=25.1.0 (deprecated in 23.1.0)

breakingDefault hashing parameters for `PasswordHasher` changed in version 21.2.0 to align with RFC 9106's low-memory profile. While old hashes remain verifiable, new hashes will use the updated, more secure defaults.

fix

No immediate fix for existing hashes, but be aware of the change for new hashes. If you need to force old defaults for new hashes (not recommended), use `argon2.profiles.PRE_21_2`. It's recommended to re-hash passwords on user login if `ph.check_needs_rehash()` indicates a need.

affects: >=21.2.0

breakingSince version 21.2.0, the CFFI bindings were extracted into `argon2-cffi-bindings`. This is a breaking change for users attempting to use a system-wide installation of Argon2 with `--no-binary`, as the argument value changed. Most users relying on default `pip install` with vendored code are unaffected.

fix

If using a system-wide Argon2, consult the installation guide for updated `--no-binary` instructions (e.g., `pip install --no-binary=argon2-cffi-bindings argon2-cffi`). Otherwise, continue with default installation.

affects: >=21.2.0

gotchaForgetting to specifically catch `argon2.exceptions.VerifyMismatchError` during password verification. This exception is raised when a submitted password does not match the stored hash, indicating a failed login attempt.

fix

Always include `except VerifyMismatchError:` in your `try...except` block when calling `ph.verify()` to handle incorrect passwords explicitly.

affects: All versions

gotchaThe `salt` parameter was added to `argon2.PasswordHasher.hash()` in v23.1.0. While available, it's generally not recommended to provide your own salt unless you have a very specific, advanced use case. The library generates secure, random salts by default.

fix

Unless you explicitly know why you need to provide a custom salt, leave the `salt` parameter as `None` to let `argon2-cffi` handle salt generation automatically.

affects: >=23.1.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'argon2._ffi'

This error occurs when the 'argon2-cffi' package is not properly installed or its dependencies are missing.

fix

Ensure 'argon2-cffi' is installed by running 'pip install argon2-cffi' and update 'cffi', 'pip', and 'setuptools' with 'pip install -U cffi pip setuptools'.

x86_64-linux-gnu-gcc: error: extras/libargon2/src/argon2.c: No such file or directory

This error indicates that the 'argon2.c' source file is missing during the build process, possibly due to an incomplete or corrupted package download.

fix

Re-download the 'argon2-cffi' package and ensure all necessary files are present before attempting installation.

Package libffi was not found in the pkg-config search path.

This error occurs when the 'libffi' development package is not installed, which is required for building 'argon2-cffi'.

fix

Install the 'libffi' development package using your system's package manager (e.g., 'sudo apt-get install libffi-dev' on Debian-based systems).

ERROR: Could not build wheels for argon2-cffi

This error typically occurs during installation on systems without a C compiler or with outdated build tools (like `pip`, `setuptools`, or `cffi`), as `argon2-cffi` depends on C extensions.

fix

On Windows, install 'Build Tools for Visual Studio' (C++ build tools component). On macOS, install 'Xcode Command Line Tools' (`xcode-select --install`). On Linux, install `build-essential` or equivalent development packages. Additionally, update `pip`, `setuptools`, and `cffi`: `python -m pip install -U pip setuptools cffi`.

ModuleNotFoundError: No module named 'argon2'

The `argon2-cffi` library is either not installed, not installed in the active Python environment, or there's an attempt to import `argon2` when a local file named `argon2.py` is shadowing the installed package. Sometimes, `ModuleNotFoundError: No module named 'argon2._ffi'` indicates a corrupted or incomplete installation.

fix

Ensure `argon2-cffi` is installed using `pip install argon2-cffi`. Verify you are using the correct Python environment. If a local `argon2.py` file exists, rename or remove it. For `argon2._ffi` errors, try updating the package: `pip install -U argon2-cffi`.

Upgrade

Version history

25.1.0latest on PyPI · released Jun 3, 2025

Audit

Dependencies

argon2-cffi-bindingsrequiredProvides the low-level CFFI bindings to the Argon2 C library; extracted into a separate project since v21.2.0.

cffioptionalUnderlying Foreign Function Interface library used by argon2-cffi-bindings.

Agent activity

57 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/hynek/argon2-cffi ↗

packagehttps://pypi.org/project/argon2-cffi/ ↗

docshttps://argon2-cffi.readthedocs.io/ ↗

changeloghttps://github.com/hynek/argon2-cffi/blob/main/CHANGELOG.md ↗