py-tlsh

library5.0.0pypypi✓ verified 86d ago

TLSH (Trend Micro Locality Sensitive Hashing) is a fuzzy hashing algorithm for similarity comparison of binary data. The py-tlsh package provides a C++ Python extension for computing and comparing TLSH hashes. Current version 4.12.1 (but a major v5.0.0 exists; see warnings). Release cadence is irregular.

data

pip install py-tlsh

github ↗package ↗

INSTALL

IMPORT

SIG · PY-TLSH

py-tlsh

datapythonv5.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 10

Env Coverage0 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v? · pip install

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

build_error

Code

Verified usage

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

tlsh

✓ import tlsh

✗ from tlsh import tlsh

The module is imported as `tlsh`, not a submodule.

Basic usage: hash creation, comparison, and validation.

import tlsh # Create a TLSH hash from a byte string data = b"hello world" hash = tlsh.hash(data) print("Hash:", hash) # Compare two hashes (similarity score) hash2 = tlsh.hash(b"hello world!") score = tlsh.diff(hash, hash2) print("Difference score:", score) # Check if a hash is valid print("Is valid:", tlsh.is_valid(hash))

Debug

Known issues

breakingTLSH v5.0.0 changed the default digest prefix to 'T1'. The v4.x series does not include the 'T1' prefix. If you upgrade to v5.0.0 (not yet on PyPI as of this writing) your hashes will be incompatible with v4.x hashes and with other tools that expect the old format.

fix

Use v4.12.1 (the latest PyPI release) unless you explicitly need v5 features. If using v5, be aware that all hashes will start with 'T1' and you may need to update storage/comparison logic.

affects: >=5.0.0

deprecatedThe function `tlsh.hash()` returns a hex string. In v5.0.0 this may change to include the 'T1' prefix. The old behavior is deprecated and will be removed in a future major release.

fix

If you need to ensure forward compatibility, consider stripping or handling the 'T1' prefix. For now, stick with v4.12.1 if you want to avoid breaking changes.

affects: >=5.0.0

gotchaThe `tlsh.diff()` function returns a difference score: 0 means identical, higher values mean more different. This is the opposite of a similarity score (0-100 typical in other libraries). Common mistake: treat the score as a similarity percentage.

fix

Use `tlsh.diff(hash1, hash2)` and interpret 0 as identical. For a similarity metric, you can invert the score (e.g., similarity = max(0, 100 - diff)) but note that the maximum difference is not fixed at 100.

affects: all

gotchaThe `tlsh.hash()` function requires a bytes-like object, not a string. Passing a plain string will raise a TypeError.

fix

Pass bytes: `tlsh.hash(b'hello')` or `tlsh.hash('hello'.encode('utf-8'))`.

affects: all

gotchaThe py-tlsh extension is compiled from C++. On some platforms (especially Windows and older Linux distros) installation may fail due to missing C++ compiler or headers. The PyPI wheel may not cover all platforms.

fix

Install a C++ compiler (e.g., 'build-essential' on Ubuntu, Xcode on macOS, Visual Studio Build Tools on Windows). For Windows, consider using the unofficial Windows binary wheels from Christoph Gohlke or install via conda.

affects: all

Errors

Common errors & fixes

TypeError: a bytes-like object is required, not 'str'

Passed a string to tlsh.hash() instead of bytes.

fix

Encode the string to bytes: `tlsh.hash('hello'.encode('utf-8'))`

ImportError: No module named tlsh

py-tlsh is not installed or installed incorrectly.

fix

Install via `pip install py-tlsh`. If that fails, ensure you have a C++ compiler (build-essential on Linux, Xcode command line tools on macOS).

ValueError: Invalid TLSH hash

Provided hash string is not a valid TLSH digest (wrong length or characters).

fix

Ensure the hash is exactly 70 hex characters (v4.x) or starts with 'T1' and is 72 characters (v5.x). Use `tlsh.is_valid(hash)` to check.

OSError: [Errno 2] No such file or directory: 'libtlsh.so'

Dynamic library not found. Usually occurs when building from source or using a non-standard installation.

fix

Reinstall py-tlsh via pip (it bundles the C extension). If using a custom build, set LD_LIBRARY_PATH or install the library system-wide.

Upgrade

Version history

5.0.0latest on PyPI · released May 8, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/trendmicro/tlsh ↗

packagehttps://pypi.org/project/py-tlsh/ ↗