Low-level CFFI bindings for Argon2

25.1.0 · active · verified Sat Mar 28

argon2-cffi-bindings provides low-level CFFI bindings to the official implementation of the Argon2 password hashing algorithm. It is primarily intended to be used as a backend dependency for high-level Python packages like `argon2-cffi`, and is not recommended for direct application password hashing. The library is actively maintained and currently at version 25.1.0, with regular releases aligning with updates to the underlying Argon2 C library and Python ecosystem changes.

Warnings

gotcha This library is NOT intended for direct use in applications for password hashing. It provides low-level CFFI bindings. For application-level password hashing, the `argon2-cffi` package (which uses these bindings) is the recommended and high-level solution.
Fix: Install and use `argon2-cffi` for password hashing: `pip install argon2-cffi`.
gotcha Direct imports for the `ffi` and `lib` objects are from the private module `_argon2_cffi_bindings`, not `argon2_cffi_bindings`. Attempting to import from the top-level package name will result in an `ImportError` or `AttributeError`.
Fix: Use `from _argon2_cffi_bindings import ffi, lib`.
gotcha For Python 3.14+ and enabling free-threading, a prerelease version of CFFI (2.0 or newer) is required. When using `uv` for installation, a special flag is needed for `argon2-cffi` (which pulls in these bindings).
Fix: When installing `argon2-cffi` with `uv` for Python 3.14+: `uv pip install --prerelease=allow argon2-cffi`. Ensure your build environment supports CFFI 2.0.
gotcha The build process automatically detects whether to use SSE2-optimized code. This detection can be overridden for cross-compiling or specific build environments using an environment variable.
Fix: Set `ARGON2_CFFI_USE_SSE2=1` to force SSE2, or `ARGON2_CFFI_USE_SSE2=0` to disable it, before installation.
deprecated Older versions of `argon2-cffi` (from which these bindings were extracted) have dropped support for Python 2.7 (version 20.1.0 was last) and Python 3.5 (version 21.1.0 was last). The `argon2-cffi-bindings` package itself requires Python >=3.9.
Fix: Upgrade to Python 3.9 or newer. Ensure your project's `python_requires` aligns with supported versions.

Install

pip install argon2-cffi-bindings Standard installation

Imports

ffi, lib
```
from _argon2_cffi_bindings import ffi, lib
```
This package is intended as an implementation detail. Its public API is deliberately placed in a private module `_argon2_cffi_bindings` to discourage direct use by end-users. Accessing `ffi` and `lib` directly is for advanced scenarios or other libraries.

Quickstart

This quickstart demonstrates how to access the `ffi` and `lib` objects from the private `_argon2_cffi_bindings` module. It emphasizes that this package is for low-level CFFI interaction, and recommends `argon2-cffi` for high-level application password hashing. The example attempts to retrieve the Argon2 C library version directly via the bindings.

from _argon2_cffi_bindings import ffi, lib

# This package is for low-level interaction with the Argon2 C library.
# For typical password hashing in applications, use 'argon2-cffi' instead.
# Example: Accessing a C function (minimal, not a full hashing example):

# Check if the Argon2 library version can be retrieved
try:
    version_major = ffi.new('unsigned int *')
    version_minor = ffi.new('unsigned int *')
    lib.argon2_get_version(version_major, version_minor)
    print(f'Argon2 C library version: {version_major[0]}.{version_minor[0]}')
except AttributeError:
    print("Could not access argon2_get_version, direct CFFI usage may vary or be unavailable.")
except Exception as e:
    print(f"An error occurred during CFFI interaction: {e}")

# A more typical usage for most Python applications would be:
# from argon2 import PasswordHasher
# ph = PasswordHasher()
# hashed_password = ph.hash('mysecretpassword')

view raw JSON →