API Reference¶

The MurmurHash3 algorithm has three variants:

MurmurHash3_x86_32: Generates 32-bit hashes using 32-bit arithmetic.
MurmurHash3_x64_128: Generates 128-bit hashes using 64-bit arithmetic.
MurmurHash3_x86_128: Generates 128-bit hashes using 32-bit arithmetic.

The mmh3 library provides functions and classes for each variant.

Although this API reference is comprehensive, you may find the following functions particularly useful:

mmh3.hash(): Uses the 32-bit variant as its backend and accepts bytes or str as input (strings are UTF-8 encoded). This function is slower than the x64_128 variant in 64-bit environments but is portable across different architectures. It can also be used to calculate favicon hash footprints for platforms like Shodan and ZoomEye.
mmh3.mmh3_x64_128_digest(): Uses the x64_128 variant as its backend. This function accepts a buffer (e.g., bytes, bytearray, memoryview, and numpy arrays) and returns a 128-bit hash as a bytes object, similar to the hashlib module in the Python Standard Library. It performs faster than the 32-bit variant on 64-bit machines.

Note that mmh3 is endian-neutral, while the original C++ library is endian-sensitive (see also Known Issues). This feature of mmh3 is essential when portability across different architectures is required, such as when calculating hash footprints for web services.

Basic Hash Functions¶

The following functions are used to hash immutable types, specifically bytes and str. String inputs are automatically converted to bytes using UTF-8 encoding before hashing.

Although hash128(), hash64(), and mmh3.hash_bytes() are provided for compatibility with previous versions and are not marked for deprecation, the buffer-accepting hashe functions introduced in version 5.0.0 are recommended for new code.

mmh3.hash(key, seed=0, signed=True) → int¶

Return a hash as a 32-bit integer.

Calculated by the MurmurHash3_x86_32 algorithm.

Parameters:

key (bytes | str) – The input data to hash.
seed (int) – The seed value. Must be an integer in the range [0, 0xFFFFFFFF].
signed (Any) – If True, return a signed integer. Otherwise, return an unsigned integer.

Returns:

The hash value as a 32-bit integer.

Return type:

int

Changed in version 5.0.0: The seed argument is now strictly checked for valid range. The type of the signed argument has been changed from bool to Any. Performance improvements have been made.

mmh3.hash128(key, seed=0, x64arch=True, signed=False) → int¶

Return a hash as a 128-bit integer.

Calculated by the MurmurHash3_x{64, 86}_128 algorithm.

Parameters:

key (bytes | str) – The input data to hash.
seed (int) – The seed value. Must be an integer in the range [0, 0xFFFFFFFF].
x64arch (Any) – If True, use an algorithm optimized for 64-bit architecture. Otherwise, use one optimized for 32-bit architecture.
signed (Any) – If True, return a signed integer. Otherwise, return an unsigned integer.

Returns:

The hash value as a 128-bit integer.

Return type:

int

Changed in version 5.0.0: The seed argument is now strictly checked for valid range. The type of the x64arch and signed arguments has been changed from bool to Any.

mmh3.hash64(key, seed=0, x64arch=True, signed=True) → tuple[int, int]¶

Return a hash as a tuple of two 64-bit integers.

Calculated by the MurmurHash3_x{64, 86}_128 algorithm.

Parameters:

key (bytes | str) – The input data to hash.
seed (int) – The seed value. Must be an integer in the range [0, 0xFFFFFFFF].
x64arch (Any) – If True, use an algorithm optimized for 64-bit architecture. Otherwise, use one optimized for 32-bit architecture.
signed (Any) – If True, return a signed integer. Otherwise, return an unsigned integer.

Returns:

The hash value as a tuple of two 64-bit integers.

Return type:

tuple[int, int]

Changed in version 5.0.0: The seed argument is now strictly checked for valid range. The type of the x64arch and signed arguments has been changed from bool to Any.

mmh3.hash_bytes(key, seed=0, x64arch=True) → bytes¶

Return a 16-byte hash of the bytes type.

Parameters:

key (bytes | str) – The input data to hash.
seed (int) – The seed value. Must be an integer in the range [0, 0xFFFFFFFF].
x64arch (Any) – If True, use an algorithm optimized for 64-bit architecture. Otherwise, use one optimized for 32-bit architecture.

Returns:

The hash value as the bytes type with a length of 16 bytes (128 bits).

Return type:

bytes

Changed in version 5.0.0: The seed argument is now strictly checked for valid range. The type of the x64arch argument has been changed from bool to Any.

Buffer-Accepting Hash Functions¶

The following functions are used to hash types that implement the buffer protocol such as bytes, bytearray, memoryview, and numpy arrays.

Hasher Classes¶

mmh3 implements hashers with interfaces similar to those in hashlib from the standard library: mmh3_32() for 32-bit hashing, mmh3_x64_128() for 128-bit hashing optimized for x64 architectures, and mmh3_x86_128() for 128-bit hashing optimized for x86 architectures.

In addition to the standard digest() method, each hasher provides sintdigest(), which returns a signed integer, and uintdigest(), which returns an unsigned integer. The 128-bit hashers also include stupledigest() and utupledigest(), which return two 64 bit integers.

Please note that as of version 5.0.0, the implementation is still experimental, and performance may be unsatisfactory (particularly mmh3_x86_128()). Additionally, hexdigest() is not supported; use digest().hex() instead.

>>> import mmh3
>>> hasher = mmh3.mmh3_x64_128(b"foo", 42) # seed=42
>>> hasher.update(b"bar")
>>> hasher.digest()
b'\x82_n\xdd \xac\xb6j\xef\x99\xb1e\xc4\n\xc9\xfd'
>>> hasher.sintdigest() # 128 bit signed int
-2943813934500665152301506963178627198
>>> hasher.uintdigest() # 128 bit unsigned int
337338552986437798311073100468589584258
>>> hasher.stupledigest() # two 64 bit signed ints
(7689522670935629698, -159584473158936081)
>>> hasher.utupledigest() # two 64 bit unsigned ints
(7689522670935629698, 18287159600550615535)

class mmh3.mmh3_32(data=None, seed=0)¶

Hasher for incrementally calculating the murmurhash3_x86_32 hash.

Parameters:

data (Buffer | None) – The initial data to hash.
seed (int) – The seed value. Must be an integer in the range [0, 0xFFFFFFFF].

Changed in version 5.0.0: Added the optional data parameter as the first argument. The seed argument is now strictly checked for valid range.

copy() → mmh3_32¶

Return a copy of the hash object..

Returns:: A copy of this hash object.
Return type:: mmh3_32

digest() → bytes¶

Return the digest value as a bytes object.

Returns:: The digest value.
Return type:: bytes

sintdigest() → int¶

Return the digest value as a signed integer.

Returns:: The digest value as a signed integer.
Return type:: int

uintdigest() → int¶

Return the digest value as an unsigned integer.

Returns:: The digest value as an unsigned integer.
Return type:: int

update(data)¶

Update this hash object’s state with the provided bytes-like object.

Parameters:: data (Buffer) – The buffer to hash.

block_size¶

Number of bytes of the internal block of this algorithm

Type:: int

digest_size¶

Number of bytes in this hashes output

Type:: int

name¶

The hash algorithm being used by this object

Type:: str

class mmh3.mmh3_x64_128(data=None, seed=0)¶

Hasher for incrementally calculating the murmurhash3_x64_128 hash.

Parameters:

data (Buffer | None) – The initial data to hash.
seed (int) – The seed value. Must be an integer in the range [0, 0xFFFFFFFF].

Changed in version 5.0.0: Added the optional data parameter as the first argument. The seed argument is now strictly checked for valid range.

copy() → mmh3_128x64¶

Return a copy of the hash object..

Returns:: A copy of this hash object.
Return type:: mmh3_128x64

digest() → bytes¶

Return the digest value as a bytes object.

Returns:: The digest value.
Return type:: bytes

sintdigest() → int¶

Return the digest value as a signed integer.

Returns:: The digest value as a signed integer.
Return type:: int

stupledigest() → tuple[int, int]¶

Return the digest value as a tuple of two signed integers.

Returns:: The digest value as a tuple of two signed integers.
Return type:: tuple[int, int]

uintdigest() → int¶

Return the digest value as an unsigned integer.

Returns:: The digest value as an unsigned integer.
Return type:: int

update(data)¶

Update this hash object’s state with the provided bytes-like object.

Parameters:: data (Buffer) – The buffer to hash.

utupledigest() → tuple[int, int]¶

Return the digest value as a tuple of two unsigned integers.

Returns:: The digest value as a tuple of two unsigned integers.
Return type:: tuple[int, int]

block_size¶

Number of bytes of the internal block of this algorithm.

Type:: int

digest_size¶

Number of bytes in this hashes output.

Type:: int

name¶

The hash algorithm being used by this object.

Type:: str

class mmh3.mmh3_x86_128(data=None, seed=0)¶

Hasher for incrementally calculating the murmurhash3_x86_128 hash.

Parameters:

data (Buffer | None) – The initial data to hash.
seed (int) – The seed value. Must be an integer in the range [0, 0xFFFFFFFF].

Changed in version 5.0.0: Added the optional data parameter as the first argument. The seed argument is now strictly checked for valid range.

copy() → mmh3_128x86¶

Return a copy of the hash object..

Returns:: A copy of this hash object.
Return type:: mmh3_128x86

digest() → bytes¶

Return the digest value as a bytes object.

Returns:: The digest value.
Return type:: bytes

sintdigest() → int¶

Return the digest value as a signed integer.

Returns:: The digest value as a signed integer.
Return type:: int

stupledigest() → tuple[int, int]¶

Return the digest value as a tuple of two signed integers.

Returns:: The digest value as a tuple of two signed integers.
Return type:: tuple[int, int]

uintdigest() → int¶

Return the digest value as an unsigned integer.

Returns:: The digest value as an unsigned integer.
Return type:: int

update(data)¶

Update this hash object’s state with the provided bytes-like object.

Parameters:: data (Buffer) – The buffer to hash.

utupledigest() → tuple[int, int]¶

Return the digest value as a tuple of two unsigned integers.

Returns:: The digest value as a tuple of two unsigned integers.
Return type:: tuple[int, int]

block_size¶

Number of bytes of the internal block of this algorithm

Type:: int

digest_size¶

Number of bytes in this hashes output

Type:: int

name¶

Te hash algorithm being used by this object

Type:: str