Low-level CFFI bindings for Argon2

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

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.

pip install argon2-cffi-bindings

Common errors

error ModuleNotFoundError: No module named 'argon2_cffi_bindings' ↓

cause The 'argon2_cffi_bindings' module is not installed in the Python environment.

fix

Install the module using pip: 'pip install argon2-cffi-bindings'.

error ERROR: Could not find a version that satisfies the requirement argon2-cffi-bindings (from versions: none) ERROR: No matching distribution found for argon2-cffi-bindings ↓

cause Attempting to install 'argon2-cffi-bindings' offline with an incompatible wheel file.

fix

Ensure the wheel file matches your Python version and architecture, or download the correct wheel file for offline installation.

error Command 'python setup.py egg_info' failed with error code 1 in /tmp/pip-build-*/argon2-cffi-bindings/ ↓

cause The installation process requires a C compiler and the 'libffi' development package, which are missing.

fix

Install the necessary build tools and 'libffi' development package for your operating system.

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

cause The source files for Argon2 are missing during the build process.

fix

Ensure all source files are present and accessible, or use a pre-built wheel to avoid building from source.

error ModuleNotFoundError: No module named '_argon2_cffi_bindings' ↓

cause This error occurs when the underlying CFFI bindings, which are a private implementation detail of `argon2-cffi`, cannot be found. This often indicates an incomplete or failed installation of `argon2-cffi` or `argon2-cffi-bindings` itself, or an environment issue (e.g., in a Docker container) preventing the module from being located.

fix

Ensure argon2-cffi is correctly installed, as it automatically pulls in and builds argon2-cffi-bindings. It's recommended to update pip, setuptools, and cffi before installation: python -m pip install -U pip setuptools cffi followed by pip install argon2-cffi. For direct low-level usage (discouraged for most applications), ensure argon2-cffi-bindings is installed correctly.

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 compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.00s 19.4M

3.10 alpine (musl) - - 0.00s 19.4M

3.10 slim (glibc) wheel 1.9s 0.00s 20M

3.10 slim (glibc) - - 0.00s 20M

3.11 alpine (musl) wheel - 0.00s 21.6M

3.11 alpine (musl) - - 0.00s 21.6M

3.11 slim (glibc) wheel 1.9s 0.00s 22M

3.11 slim (glibc) - - 0.00s 22M

3.12 alpine (musl) wheel - 0.00s 13.4M

3.12 alpine (musl) - - 0.00s 13.4M

3.12 slim (glibc) wheel 1.7s 0.00s 14M

3.12 slim (glibc) - - 0.00s 14M

3.13 alpine (musl) wheel - 0.00s 13.1M

3.13 alpine (musl) - - 0.00s 13.0M

3.13 slim (glibc) wheel 1.7s 0.00s 14M

3.13 slim (glibc) - - 0.00s 14M

3.9 alpine (musl) wheel - 0.00s 19.7M

3.9 alpine (musl) - - 0.00s 19.7M

3.9 slim (glibc) wheel 2.3s 0.00s 20M

3.9 slim (glibc) - - 0.00s 20M

Imports

ffi, lib
wrong
```
from argon2_cffi_bindings import ffi, lib
```
correct
```
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 verified last tested: 2026-04-24

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')