Skip to main content

Python binding for xxHash

Project description

Github Actions Status Latest Version Supported Python versions License

xxhash is a Python binding for the xxHash library by Yann Collet.


$ pip install xxhash

Installing From Source

$ pip install --no-binary xxhash xxhash


On Debian/Ubuntu:

$ apt-get install python-dev gcc

On CentOS/Fedora:

$ yum install python-devel gcc redhat-rpm-config

Linking to

By default python-xxhash will use bundled xxHash, we can change this by specifying ENV var XXHASH_LINK_SO:

$ XXHASH_LINK_SO=1 pip install --no-binary xxhash xxhash


Module version and its backend xxHash library version can be retrieved using the module properties VERSION AND XXHASH_VERSION respectively.

>>> import xxhash
>>> xxhash.VERSION

This module is hashlib-compliant, which means you can use it in the same way as hashlib.md5.

update() – update the current digest with an additional string
digest() – return the current digest value
hexdigest() – return the current digest as a string of hexadecimal digits
intdigest() – return the current digest as an integer
copy() – return a copy of the current xxhash object
reset() – reset state

md5 digest returns bytes, but the original xxh32 and xxh64 C APIs return integers. While this module is made hashlib-compliant, intdigest() is also provided to get the integer digest.

Constructors for hash algorithms provided by this module are xxh32() and xxh64().

For example, to obtain the digest of the byte string b'Nobody inspects the spammish repetition':

>>> import xxhash
>>> x = xxhash.xxh32()
>>> x.update(b'Nobody inspects')
>>> x.update(b' the spammish repetition')
>>> x.digest()
>>> x.digest_size
>>> x.block_size

More condensed:

>>> xxhash.xxh32(b'Nobody inspects the spammish repetition').hexdigest()
>>> xxhash.xxh32(b'Nobody inspects the spammish repetition').digest() == x.digest()

An optional seed (default is 0) can be used to alter the result predictably:

>>> import xxhash
>>> xxhash.xxh64('xxhash').hexdigest()
>>> xxhash.xxh64('xxhash', seed=20141025).hexdigest()
>>> x = xxhash.xxh64(seed=20141025)
>>> x.update('xxhash')
>>> x.hexdigest()
>>> x.intdigest()

Be careful that xxh32 takes an unsigned 32-bit integer as seed, while xxh64 takes an unsigned 64-bit integer. Although unsigned integer overflow is defined behavior, it’s better not to make it happen:

>>> xxhash.xxh32('I want an unsigned 32-bit seed!', seed=0).hexdigest()
>>> xxhash.xxh32('I want an unsigned 32-bit seed!', seed=2**32).hexdigest()
>>> xxhash.xxh32('I want an unsigned 32-bit seed!', seed=1).hexdigest()
>>> xxhash.xxh32('I want an unsigned 32-bit seed!', seed=2**32+1).hexdigest()
>>> xxhash.xxh64('I want an unsigned 64-bit seed!', seed=0).hexdigest()
>>> xxhash.xxh64('I want an unsigned 64-bit seed!', seed=2**64).hexdigest()
>>> xxhash.xxh64('I want an unsigned 64-bit seed!', seed=1).hexdigest()
>>> xxhash.xxh64('I want an unsigned 64-bit seed!', seed=2**64+1).hexdigest()

digest() returns bytes of the big-endian representation of the integer digest:

>>> import xxhash
>>> h = xxhash.xxh64()
>>> h.digest()
>>> h.intdigest().to_bytes(8, 'big')
>>> h.hexdigest()
>>> format(h.intdigest(), '016x')
>>> h.intdigest()
>>> int(h.hexdigest(), 16)

Besides xxh32/xxh64 mentioned above, oneshot functions are also provided, so we can avoid allocating XXH32/64 state on heap:

xxh32_digest(bytes, seed=0)
xxh32_intdigest(bytes, seed=0)
xxh32_hexdigest(bytes, seed=0)
xxh64_digest(bytes, seed=0)
xxh64_intdigest(bytes, seed=0)
xxh64_hexdigest(bytes, seed=0)
>>> import xxhash
>>> xxhash.xxh64('a').digest() == xxhash.xxh64_digest('a')
>>> xxhash.xxh64('a').intdigest() == xxhash.xxh64_intdigest('a')
>>> xxhash.xxh64('a').hexdigest() == xxhash.xxh64_hexdigest('a')
>>> xxhash.xxh64_hexdigest('xxhash', seed=20141025)
>>> xxhash.xxh64_intdigest('xxhash', seed=20141025)
>>> xxhash.xxh64_digest('xxhash', seed=20141025)
In [1]: import xxhash

In [2]: %timeit xxhash.xxh64_hexdigest('xxhash')
268 ns ± 24.1 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)

In [3]: %timeit xxhash.xxh64('xxhash').hexdigest()
416 ns ± 17.3 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)

XXH3 hashes are available since v2.0.0 (xxHash v0.8.0), they are:

Streaming classes:


Oneshot functions:

xxh3_64_digest(bytes, seed=0)
xxh3_64_intdigest(bytes, seed=0)
xxh3_64_hexdigest(bytes, seed=0)
xxh3_128_digest(bytes, seed=0)
xxh3_128_intdigest(bytes, seed=0)
xxh3_128_hexdigest(bytes, seed=0)

And aliases:

xxh128 = xxh3_128
xxh128_digest = xxh3_128_digest
xxh128_intdigest = xxh3_128_intdigest
xxh128_hexdigest = xxh3_128_hexdigest



xxh32 takes an unsigned 32-bit integer as seed, and xxh64 takes an unsigned 64-bit integer as seed. Make sure that the seed is greater than or equal to 0.


As of python-xxhash 0.3.0, digest() returns bytes of the big-endian representation of the integer digest. It used to be little-endian.


Though you can use xxhash as an HMAC hash function, but it’s highly recommended not to.

xxhash is NOT a cryptographic hash function, it is a non-cryptographic hash algorithm aimed at speed and quality. Do not put xxhash in any position where cryptographic hash functions are required.


v3.0.0 2022-02-25

  • New set algorithms_available lists all implemented algorithms in xxhash package.
  • Upgrade xxHash to v0.8.1.
  • Drop support for EOL Python versions, require python >= 3.6 from now on.
  • Migrate to github actions and build arm64 wheels for macOS.
  • Always release GIL.

v2.0.2 2021-04-15

  • Fix Travis CI OSX dpl python2.7 error

v2.0.1 2021-04-15

  • Only to trigger Python 3.9 wheels building.

v2.0.0 2020-08-03

  • Require xxHash version >= v0.8.0
  • Upgrade xxHash to v0.8.0
  • XXH3 hashes: xxh3_64, xxh3_128, and their oneshot functions

v1.4.4 2020-06-20

  • Upgrade xxHash to v0.7.3
  • Stop using PEP393 deprecated APIs
  • Use XXH(32|64)_canonicalFromHash to replace u2bytes and ull2bytes

v1.4.3 2019-11-12

  • Upgrade xxHash to v0.7.2
  • Python 3.8 wheels

v1.4.2 2019-10-13

  • Fixed: fails when reading README.rst and the default encoding is not UTF-8

v1.4.1 2019-08-27

  • Fixed: xxh3.h in missing from source tarball

v1.4.0 2019-08-25

  • Upgrade xxHash to v0.7.1

v1.3.0 2018-10-21

v1.2.0 2018-07-13

  • Add oneshot functions xxh{32,64}_{,int,hex}digest

v1.1.0 2018-07-05

  • Allow input larger than 2GB
  • Release the GIL on sufficiently large input
  • Drop support for Python 3.2

v1.0.1 2017-03-02

  • Free state actively, instead of delegating it to ffi.gc

v1.0.0 2017-02-10

  • Fixed copy() segfault
  • Added CFFI variant

v0.6.3 2017-02-10

  • Fixed copy() segfault

v0.6.2 2017-02-10

  • Upgrade xxHash to v0.6.2

v0.6.1 2016-06-26

  • Upgrade xxHash to v0.6.1

v0.5.0 2016-03-02

  • Upgrade xxHash to v0.5.0

v0.4.3 2015-08-21

  • Upgrade xxHash to r42

v0.4.1 2015-08-16

  • Upgrade xxHash to r41

v0.4.0 2015-08-05

  • Added method reset
  • Upgrade xxHash to r40

v0.3.2 2015-01-27

  • Fixed some typos in docstrings

v0.3.1 2015-01-24

  • Upgrade xxHash to r39

v0.3.0 2014-11-11

  • Change digest() from little-endian representation to big-endian representation of the integer digest. This change breaks compatibility (digest() results are different).

v0.2.0 2014-10-25

  • Make this package hashlib-compliant

v0.1.3 2014-10-23

  • Update xxHash to r37

v0.1.2 2014-10-19

  • Improve: Check XXHnn_init() return value.
  • Update xxHash to r36

v0.1.1 2014-08-07

  • Improve: Can now be built with Visual C++ Compiler.

v0.1.0 2014-08-05

  • New: XXH32 and XXH64 type, which support partially update.
  • Fix: build under Python 3.4

v0.0.2 2014-08-03

  • NEW: Support Python 3

v0.0.1 2014-07-30

  • NEW: xxh32 and xxh64

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

xxhash-3.0.0.tar.gz (74.3 kB view hashes)

Uploaded source

Built Distributions

xxhash-3.0.0-pp38-pypy38_pp73-win_amd64.whl (53.7 kB view hashes)

Uploaded pp38

xxhash-3.0.0-pp37-pypy37_pp73-win_amd64.whl (53.7 kB view hashes)

Uploaded pp37

xxhash-3.0.0-cp310-cp310-win_amd64.whl (29.9 kB view hashes)

Uploaded cp310

xxhash-3.0.0-cp310-cp310-win32.whl (30.2 kB view hashes)

Uploaded cp310

xxhash-3.0.0-cp39-cp39-win_amd64.whl (29.9 kB view hashes)

Uploaded cp39

xxhash-3.0.0-cp39-cp39-win32.whl (30.2 kB view hashes)

Uploaded cp39

xxhash-3.0.0-cp39-cp39-macosx_11_0_arm64.whl (30.7 kB view hashes)

Uploaded cp39

xxhash-3.0.0-cp38-cp38-win_amd64.whl (29.9 kB view hashes)

Uploaded cp38

xxhash-3.0.0-cp38-cp38-win32.whl (30.2 kB view hashes)

Uploaded cp38

xxhash-3.0.0-cp38-cp38-macosx_11_0_arm64.whl (30.7 kB view hashes)

Uploaded cp38

xxhash-3.0.0-cp37-cp37m-win_amd64.whl (29.9 kB view hashes)

Uploaded cp37

xxhash-3.0.0-cp37-cp37m-win32.whl (30.2 kB view hashes)

Uploaded cp37

xxhash-3.0.0-cp36-cp36m-win_amd64.whl (41.5 kB view hashes)

Uploaded cp36

xxhash-3.0.0-cp36-cp36m-win32.whl (42.2 kB view hashes)

Uploaded cp36

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page