{"id":462,"library":"argon2-cffi","title":"argon2-cffi","description":"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.","status":"active","version":"25.1.0","language":"python","source_language":"en","source_url":"https://github.com/hynek/argon2-cffi","tags":["security","password-hashing","cryptography","argon2"],"install":[{"cmd":"pip install argon2-cffi","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Provides the low-level CFFI bindings to the Argon2 C library; extracted into a separate project since v21.2.0.","package":"argon2-cffi-bindings"},{"reason":"Underlying Foreign Function Interface library used by argon2-cffi-bindings.","package":"cffi","optional":true}],"imports":[{"note":"This is the primary class for hashing and verifying passwords.","symbol":"PasswordHasher","correct":"from argon2 import PasswordHasher"},{"note":"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`.","wrong":"except Exception as e:","symbol":"VerifyMismatchError","correct":"from argon2.exceptions import VerifyMismatchError"}],"quickstart":{"code":"from argon2 import PasswordHasher\nfrom argon2.exceptions import VerifyMismatchError\n\nph = PasswordHasher()\n\n# Hash a password\npassword = \"correct horse battery staple\"\nhashed_password = ph.hash(password)\nprint(f\"Hashed: {hashed_password}\")\n\n# Verify a password\ntry:\n    ph.verify(hashed_password, password)\n    print(\"Verification successful!\")\nexcept VerifyMismatchError:\n    print(\"Verification failed: Password does not match.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred during verification: {e}\")\n\n# Check if a rehash is needed (e.g., if parameters changed)\nif ph.check_needs_rehash(hashed_password):\n    print(\"Password needs re-hashing with new parameters.\")\nelse:\n    print(\"Password hash parameters are up-to-date.\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to Python 3.8 or newer. Ensure your project's `requires_python` matches.","message":"Python 2.7, 3.4, 3.5, and 3.7 are no longer supported. The minimum Python version is now 3.8.","severity":"breaking","affected_versions":"<=25.0.0 (specific removals: 2.7 in 21.1.0, 3.5 in 21.2.0, 3.7 in 25.1.0)"},{"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()`.","message":"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.","severity":"breaking","affected_versions":">=25.1.0 (deprecated in 23.1.0)"},{"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.","message":"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.","severity":"breaking","affected_versions":">=21.2.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=21.2.0"},{"fix":"Always include `except VerifyMismatchError:` in your `try...except` block when calling `ph.verify()` to handle incorrect passwords explicitly.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=23.1.0"}],"env_vars":null,"last_verified":"2026-05-12T13:58:08.880Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"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'.","cause":"This error occurs when the 'argon2-cffi' package is not properly installed or its dependencies are missing.","error":"ModuleNotFoundError: No module named 'argon2._ffi'"},{"fix":"Re-download the 'argon2-cffi' package and ensure all necessary files are present before attempting installation.","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.","error":"x86_64-linux-gnu-gcc: error: extras/libargon2/src/argon2.c: No such file or directory"},{"fix":"Install the 'libffi' development package using your system's package manager (e.g., 'sudo apt-get install libffi-dev' on Debian-based systems).","cause":"This error occurs when the 'libffi' development package is not installed, which is required for building 'argon2-cffi'.","error":"Package libffi was not found in the pkg-config search path."},{"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`.","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.","error":"ERROR: Could not build wheels for argon2-cffi"},{"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`.","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.","error":"ModuleNotFoundError: No module named 'argon2'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.1,"disk_size":"19.6M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":2.1,"disk_size":"20M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":2,"disk_size":"21.7M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":2,"disk_size":"22M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.8,"disk_size":"13.5M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.8,"disk_size":"14M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2.2,"disk_size":"13.2M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2,"disk_size":"14M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2,"disk_size":"19.8M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2,"disk_size":"20M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}