Install & Compatibility
Where this runs
tested against v0.5.1 · 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
py 3.10
✕ build_error
✕ build_error
py 3.11
✕ build_error
✓ 1.6s
py 3.12
✕ build_error
✓ 1.4s
py 3.13
✕ build_error
✓ 1.5s
py 3.9
✕ build_error
✕ build_error
15MB installed
● package 15MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
farmhash
✓ import farmhash
The primary module containing all hashing functions.
hash64
✓ import farmhash
farmhash.hash64('input')
One of the main 64-bit hashing functions.
fingerprint64
✓ import farmhash
farmhash.fingerprint64(b'input')
✗ farmhash.fingerprint64('input')
Functions like `fingerprint64` expect byte strings as input; passing a regular Python string will raise a TypeError.
This quickstart demonstrates basic usage of `pyfarmhash` for 32-bit and 64-bit hashing, including using seeds and the critical distinction between string and byte string inputs for different function types.
import farmhash
# Hashing a standard string (utf-8 encoded by default for hash functions)
text_input = 'Hello, FarmHash!'
hash_value_64 = farmhash.hash64(text_input)
hash_value_32 = farmhash.hash32(text_input)
print(f"Hash64 for '{text_input}': {hash_value_64}")
print(f"Hash32 for '{text_input}': {hash_value_32}")
# Hashing a byte string (required for fingerprint functions)
bytes_input = b'Another test string'
fingerprint_64 = farmhash.fingerprint64(bytes_input)
fingerprint_32 = farmhash.fingerprint32(bytes_input)
print(f"Fingerprint64 for '{bytes_input.decode()}': {fingerprint_64}")
print(f"Fingerprint32 for '{bytes_input.decode()}': {fingerprint_32}")
# Hashing with a seed
seeded_hash = farmhash.hash64withseed(text_input, 12345)
print(f"Seeded Hash64 for '{text_input}' with seed 12345: {seeded_hash}")
Debug
Known issues
gotchaMany `pyfarmhash` functions, especially `fingerprint` variants, strictly require byte strings (`bytes`) as input. Passing a regular Python string (`str`) will result in a `TypeError`. Remember to encode strings (e.g., `my_string.encode('utf-8')`) before passing them to these functions.fixAlways encode string inputs to bytes using `.encode('utf-8')` (or another appropriate encoding) before calling byte-specific hashing functions like `farmhash.fingerprint64()`. affects: All versions
gotchaWhen installing `pyfarmhash` from source (not using pre-built wheels), a C++ compiler is required (`g++` on Linux/macOS, Microsoft Visual C++ Compiler on Windows). Setting up the build environment on Windows can be particularly complex.fixPrefer `pip install pyfarmhash` to leverage pre-built wheels. If building from source, ensure your C++ compiler and associated build tools are correctly installed and configured for your Python environment. For Windows, consider the detailed (and often 'hacky') instructions in the GitHub README if pre-built wheels are not an option.
affects: All versions (when building from source)
gotchaFarmHash is a non-cryptographic hash function. This means it is optimized for speed and distribution, but it is not designed to be collision-resistant and should NOT be used for security-sensitive applications like password hashing or data integrity verification where cryptographic strength is needed.fixUse cryptographic hash functions (e.g., from Python's `hashlib` module) for security-critical tasks. FarmHash is suitable for tasks like data deduplication, partitioning, and unique identifier generation in non-security contexts.
affects: All versions
gotchaDiscrepancies can occur when comparing `pyfarmhash` output with Google BigQuery's `FARM_FINGERPRINT` function, particularly regarding the handling of unsigned 64-bit integers vs. signed integers in Python. BigQuery might return a signed representation where `pyfarmhash` returns an unsigned one.fixIf matching BigQuery's `FARM_FINGERPRINT` output is critical, explicitly convert the `pyfarmhash` output to a signed 64-bit integer using `numpy.uint64(hash_value).astype('int64')`. affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pyfarmhash'
The 'pyfarmhash' module is not installed in the Python environment.
fixInstall the module using pip: 'pip install pyfarmhash'.
ImportError: /path/to/pyfarmhash.so: undefined symbol: PyFPE_jbuf
The compiled 'pyfarmhash' shared object file references an undefined symbol, possibly due to a mismatch between Python versions or missing dependencies.
fixEnsure that 'pyfarmhash' is compiled and installed using the same Python version as the runtime environment, and that all necessary dependencies are present.
ImportError: /path/to/pyfarmhash.so: undefined symbol: _Py_ZeroStruct
The 'pyfarmhash' shared object file is referencing an undefined symbol, likely due to a mismatch between the compiled extension and the Python interpreter.
fixRecompile 'pyfarmhash' with the correct Python headers and ensure compatibility between the compiled extension and the Python interpreter.
TypeError: argument 1 must be bytes, not str
Many `pyfarmhash` functions, particularly `fingerprint` variants, strictly require byte strings (`bytes`) as input, but a regular Python string (`str`) was provided.
fixAlways encode string inputs to bytes using `.encode('utf-8')` (or another appropriate encoding) before calling byte-specific hashing functions like `farmhash.fingerprint64()`. ERROR: Failed building wheel for pyfarmhash
`pyfarmhash` is a C extension and requires a C++ compiler (e.g., g++ on Linux/macOS, Microsoft Visual C++ Build Tools on Windows) to compile from source if a pre-built wheel is not available or compatible for your system and Python version.
fixEnsure you have a compatible C++ compiler installed and correctly configured for your Python environment. For Windows, install Microsoft Visual C++ Build Tools. Preferably, use `pip install pyfarmhash` to leverage pre-built wheels, which do not require local compilation.
Upgrade
Version history
0.5.1latest on PyPI · released Aug 26, 2026
Audit
Dependencies
g++optionalRequired for building from source on Linux/macOS.
Microsoft Visual C++ CompileroptionalRequired for building from source on Windows (though pre-built wheels are available).