mmh3
is a Python extension for
MurmurHash (MurmurHash3), a set of
fast and robust non-cryptographic hash functions invented by Austin Appleby.
By combining mmh3
with probabilistic techniques like
Bloom filter,
MinHash, and
feature hashing, you can
develop high-performance systems in fields such as data mining, machine
learning, and natural language processing.
Another popular use of mmh3
is to
calculate favicon hashes,
which are utilized by Shodan, the world's first IoT
search engine.
This page provides a quick start guide. For more comprehensive information, please refer to the documentation.
pip install mmh3
>>> import mmh3
>>> mmh3.hash("foo") # returns a 32-bit signed int
-156908512
>>> mmh3.hash("foo", 42) # uses 42 as the seed
-1322301282
>>> mmh3.hash("foo", signed=False) # returns a 32-bit unsigned int
4138058784
Other functions:
>>> mmh3.hash64("foo") # two 64-bit signed ints using the 128-bit algorithm
(-2129773440516405919, 9128664383759220103)
>>> mmh3.hash64("foo", signed=False) # two 64-bit unsigned ints
(16316970633193145697, 9128664383759220103)
>>> mmh3.hash128("foo", 42) # 128-bit unsigned int
215966891540331383248189432718888555506
>>> mmh3.hash128("foo", 42, signed=True) # 128-bit signed int
-124315475380607080215185174712879655950
>>> mmh3.hash_bytes("foo") # 128-bit value as bytes
'aE\xf5\x01W\x86q\xe2\x87}\xba+\xe4\x87\xaf~'
>>> import numpy as np
>>> a = np.zeros(2 ** 32, dtype=np.int8)
>>> mmh3.hash_bytes(a)
b'V\x8f}\xad\x8eNM\xa84\x07FU\x9c\xc4\xcc\x8e'
Beware that hash64
returns two values, because it uses the 128-bit version
of MurmurHash3 as its backend.
hash_from_buffer
hashes byte-likes without memory copying. The method is
suitable when you hash a large memory-view such as numpy.ndarray
.
>>> mmh3.hash_from_buffer(numpy.random.rand(100))
-2137204694
>>> mmh3.hash_from_buffer(numpy.random.rand(100), signed=False)
3812874078
hash64
, hash128
, and hash_bytes
have the third argument for architecture
optimization (keyword arg: x64arch
). Use True for x64 and False for x86
(default: True):
>>> mmh3.hash64("foo", 42, True)
(-840311307571801102, -6739155424061121879)
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 4.1.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(seed=42)
>>> hasher.update(b"foo")
>>> hasher.update(b"bar")
>>> hasher.update("foo") # str inputs are not allowed for hashers
TypeError: Strings must be encoded before hashing
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
>>> 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)
See Changelog for the complete changelog.
- Add
digest
functions that accept a non-immutable buffer as input and process it without internal copying (#75). - Slightly improve the performance of the
hash_bytes
function. - Add support for Python 3.13.
- Add Read the Docs documentation (#54).
- (planned: Document benchmark results (#53)).
- Change the format of CHANGELOG.md to conform to the Keep a Changelog standard (#63).
- Fix a reference leak in the
hash_from_buffer()
function (#75). - Fix type hints.
4.1.0 - 2024-01-09
- Add support for Python 3.12.
- Fix issues with Bazel by changing the directory structure of the project (#50).
- Fix incorrect type hints (#51).
- Fix invalid results on s390x when the arg
x64arch
ofhash64
orhash_bytes
is set toFalse
(#52).
4.0.1 - 2023-07-14
- Refactor the project structure (#48).
- Fix incorrect type hints.
MIT, unless otherwise noted within a file.
By default, mmh3
returns signed values for the 32-bit and 64-bit versions
and unsigned values for hash128
due to historical reasons. To get the
desired result, use the signed
keyword argument.
Starting from version 4.0.0, mmh3
returns the same values on big-endian
platforms as it does on little-endian ones, whereas the original C++ library is
endian-sensitive. If you need results that comply with the original library on
big-endian systems, please use version 3.*.
For compatibility with Google Guava (Java), see https://stackoverflow.com/questions/29932956/murmur3-hash-different-result-between-python-and-java-implementation.
For compatibility with murmur3 (Go), see #46.
In version 2.4, the type of a seed was changed from a signed 32-bit integer to an unsigned 32-bit integer. However, the resulting values for signed seeds remain unchanged from previous versions, as long as they are 32-bit.
>>> mmh3.hash("aaaa", -1756908916) # signed representation for 0x9747b28c
1519878282
>>> mmh3.hash("aaaa", 2538058380) # unsigned representation for 0x9747b28c
1519878282
Be careful so that these seeds do not exceed 32-bit. Unexpected results may happen with invalid values.
>>> mmh3.hash("foo", 2 ** 33)
-156908512
>>> mmh3.hash("foo", 2 ** 34)
-156908512
See Contributing.
MurmurHash3 was originally developed by Austin Appleby and distributed under public domain https://github.com/aappleby/smhasher.
Ported and modified for Python by Hajime Senuma.
The following textbooks and tutorials are great resources for learning how to
use mmh3
(and other hash algorithms in general) for high-performance computing.
- Chapter 11: Using Less Ram in Micha Gorelick and Ian Ozsvald. 2014. High
Performance Python: Practical Performant Programming for Humans. O'Reilly
Media. ISBN: 978-1-4493-6159-4.
- 2nd edition of the above (2020). ISBN: 978-1492055020.
- Max Burstein. February 2, 2013. Creating a Simple Bloom Filter.
- Duke University. April 14, 2016. Efficient storage of data in memory.
- Bugra Akyildiz. August 24, 2016. A Gentle Introduction to Bloom Filter. KDnuggets.
Shodan, the world's first IoT search engine, uses MurmurHash3 hash values for favicons (icons associated with web pages). ZoomEye follows Shodan's convention. Calculating these values with mmh3 is useful for OSINT and cybersecurity activities.
- Jan Kopriva. April 19, 2021. Hunting phishing websites with favicon hashes. SANS Internet Storm Center.
- Nikhil Panwar. May 2, 2022. Using Favicons to Discover Phishing & Brand Impersonation Websites. Bolster.
- Faradaysec. July 25, 2022. Understanding Spring4Shell: How used is it?. Faraday Security.
- Debjeet. August 2, 2022. How To Find Assets Using Favicon Hashes. Payatu.
- https://github.com/wc-duck/pymmh3: mmh3 in pure python (Fredrik Kihlander and Swapnil Gusani)
- https://github.com/escherba/python-cityhash: Python bindings for CityHash (Eugene Scherba)
- https://github.com/veelion/python-farmhash: Python bindings for FarmHash (Veelion Chong)
- https://github.com/escherba/python-metrohash: Python bindings for MetroHash (Eugene Scherba)
- https://github.com/ifduyue/python-xxhash: Python bindings for xxHash (Yue Du)