cityhash

library0.4.10pypypi✓ verified 23d ago

CityHash is a family of fast non-cryptographic hash functions for strings, originally developed by Google. FarmHash is a successor designed for improved performance and collision resistance on modern CPUs. This library, `python-cityhash`, provides Python bindings for both CityHash and FarmHash, enabling high-performance hashing in Python applications. It is currently at version 0.4.10 and receives updates for Python version compatibility and Cython build fixes.

serialization data

pip install cityhash

github ↗package ↗

INSTALL

IMPORT

SIG · CITYHASH

cityhash

serializationpythonv0.4.10

Install

1.6s avg

Import

—

Disk

18MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.4.10 · 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

musl

py 3.10–3.95 runs

build_error

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.000s · 20MB

18MB installed

● package 18MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CityHash32

✓ from cityhash import CityHash32

CityHash64

✓ from cityhash import CityHash64

CityHash128

✓ from cityhash import CityHash128

FarmHash32

✓ from farmhash import FarmHash32

FarmHash64

✓ from farmhash import FarmHash64

FarmHash128

✓ from farmhash import FarmHash128

Fingerprint128

✓ from farmhash import Fingerprint128

CityHashCrc128

✓ from cityhash.cityhashcrc import CityHashCrc128

CityHashCrc256

✓ from cityhash.cityhashcrc import CityHashCrc256

This example demonstrates how to use CityHash and FarmHash functions. It highlights the necessity of encoding strings to bytes and converting integers to a fixed-size byte representation for consistent hashing.

import cityhash import farmhash # Hashing a string (must be encoded to bytes) data_string = "hello world" hashed_bytes = cityhash.CityHash64(data_string.encode('utf-8')) print(f"CityHash64 of '{data_string}': {hashed_bytes}") # Hashing bytes directly data_bytes = b"another example" hashed_bytes_128 = cityhash.CityHash128(data_bytes) print(f"CityHash128 of '{data_bytes.decode()}': {hashed_bytes_128}") # Hashing with FarmHash farm_hash_64 = farmhash.FarmHash64(b"farmhash test") print(f"FarmHash64 of 'farmhash test': {farm_hash_64}") # Hashing an integer (must be converted to fixed-size bytes) int_data = 123456789 hashed_int = cityhash.CityHash64(int_data.to_bytes(8, 'big')) print(f"CityHash64 of integer {int_data}: {hashed_int}")

Debug

Known issues

breakingVersion 0.4.0 dropped support for Python 2. Projects targeting Python 2 must use an older version of the library (e.g., <0.4.0).

fix

Upgrade to Python 3 or pin the library version to <0.4.0 if Python 2 compatibility is essential.

affects: >=0.4.0

gotchaCityHash and FarmHash functions operate on byte strings, not Python unicode strings. Attempting to hash a string directly will result in a TypeError or incorrect results. Always encode strings to bytes (e.g., `my_string.encode('utf-8')`) before passing them to hashing functions.

fix

Ensure all string inputs are explicitly encoded to bytes using a consistent encoding (e.g., `my_string.encode('utf-8')`).

affects: All

gotchaWhen hashing integers, convert them to a fixed-size byte representation (e.g., 8 bytes for CityHash64) for consistent and reproducible results. Variable-length byte representations can lead to inconsistent hashes.

fix

Convert integers to a fixed-size byte sequence: `integer_value.to_bytes(8, 'big')` (or 'little' depending on desired endianness).

affects: All

gotchaThis implementation of CityHash and FarmHash does not support incremental hashing. They are not suitable for hashing long character streams or data that arrives in chunks. For incremental hashing, consider libraries like MetroHash or xxHash.

fix

For stream processing or incremental hashing needs, use a library that explicitly supports this feature (e.g., MetroHash or xxHash).

affects: All

gotchaCityHash and FarmHash are *non-cryptographic* hash functions. They are optimized for speed and good distribution, but they are not designed to be collision-resistant and should NOT be used for security-sensitive applications like password storage or digital signatures.

fix

For cryptographic security requirements, use standard library `hashlib` functions (e.g., SHA256, Blake2b).

affects: All

gotchaWhen hashing NumPy arrays or other objects exposing the Python Buffer Protocol, ensure the array is contiguous in memory. Non-contiguous arrays might lead to unexpected results.

fix

Use `numpy.ascontiguousarray()` to convert non-contiguous arrays before hashing: `cityhash.CityHash64(numpy.ascontiguousarray(arr))`.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'cityhash'

The `cityhash` Python package is not installed in the current Python environment or is not accessible via the Python path.

fix

pip install cityhash

Failed building wheel for cityhash

The `cityhash` package, which contains C/C++ extensions, failed to compile during installation. This typically happens when necessary build tools (like a C++ compiler, Python development headers, or Cython) are missing from the system.

fix

Ensure you have a C++ compiler (e.g., build-essential on Linux, Xcode Command Line Tools on macOS, or Visual C++ Build Tools on Windows) and Python development headers installed. Then retry installation:
On Linux/macOS: `sudo apt-get install build-essential python3-dev` (for Python 3) or `sudo yum install gcc-c++ python3-devel`
On Windows: Install 'Desktop development with C++' workload from Visual Studio Installer.
After dependencies are met: `pip install cityhash`

TypeError: argument 1 must be bytes, not str

CityHash and FarmHash functions operate on byte sequences. Passing a Python string directly without encoding it first will result in a TypeError.

fix

Encode your string to bytes before passing it to the hash function, typically using UTF-8 encoding. For example: `cityhash.CityHash64('your string'.encode('utf-8'))`

src/cityhash.cpp:2628:17: error: 'PyUnicode_AsUTF8AndSize' was not declared in this scope

This is a compilation error during installation, often due to a mismatch between the CPython API being used by the `python-cityhash` Cython code and the Python version's headers or the compiler's understanding of them. It sometimes indicates an older Python version or a build environment issue.

fix

Ensure you are using a Python version supported by the latest `cityhash` (currently Python 3.6+). Upgrade `pip` and `setuptools` to their latest versions: `pip install --upgrade pip setuptools wheel`. If the problem persists, ensure your C++ compiler and Python development headers are correctly configured and up-to-date for your Python installation.

Upgrade

Version history

0.4.10latest on PyPI · released Oct 9, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/escherba/python-cityhash ↗

packagehttps://pypi.org/project/cityhash/ ↗