argon2-cffi

25.1.0 verified Tue May 12 auth: no python install: verified quickstart: verified

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.

pip install argon2-cffi

Common errors

error ModuleNotFoundError: No module named 'argon2._ffi' ↓

cause 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'.

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

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

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

cause 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 ERROR: Could not build wheels for argon2-cffi ↓

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

error ModuleNotFoundError: No module named 'argon2' ↓

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

Warnings

breaking Python 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.

breaking The 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()`.

breaking Default 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.

breaking Since 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.

gotcha Forgetting 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.

gotcha The `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.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.04s 19.6M

3.10 slim (glibc) - - 0.03s 20M

3.11 alpine (musl) - - 0.08s 21.7M

3.11 slim (glibc) - - 0.06s 22M

3.12 alpine (musl) - - 0.06s 13.5M

3.12 slim (glibc) - - 0.06s 14M

3.13 alpine (musl) - - 0.05s 13.2M

3.13 slim (glibc) - - 0.05s 14M

3.9 alpine (musl) - - 0.04s 19.8M

3.9 slim (glibc) - - 0.04s 20M

Imports

PasswordHasher
```
from argon2 import PasswordHasher
```
This is the primary class for hashing and verifying passwords.
VerifyMismatchError
wrong
```
except Exception as e:
```
correct
```
from argon2.exceptions import VerifyMismatchError
```
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`.

Quickstart verified last tested: 2026-04-23

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.")