---
id: py-tlsh
version: "5.0.0"
license: Apache or BSD
license_treatment: permissive
maintenance: active
---

# py-tlsh — TLSH (C++ Python extension)

License: permissive · Maintenance: active · Downloads: 102.1K/mo

## What it is and what it does

py-tlsh is a Python binding to the TLSH (Trend Micro Locality Sensitive Hash) C++ library, a fuzzy matching algorithm designed for binary data. It generates hash values from byte streams that preserve similarity—similar inputs produce similar hashes—enabling detection of related objects by comparing hash values rather than doing byte-for-byte comparison. The library requires a minimum of 50 bytes of input with sufficient randomness to generate a valid hash; it will not hash uniform or near-uniform data.

The package is a C++ extension, so installation requires compilation on the target system. It provides both simple one-shot hashing via tlsh.hash() and streaming hashing via the Tlsh class for processing large files incrementally. It supports multiple hash formats including the current T1 format and older formats for backwards compatibility, and offers variants like diffxlen() for length-independent comparison and conservativehash() for stricter randomness requirements.

Use it for:

- Detect similar malware samples or suspicious files by comparing TLSH hashes instead of exact signatures
- Find near-duplicate documents or data blobs in large datasets without full content comparison
- Stream-hash large files incrementally to avoid loading entire contents into memory
- Compare binary artifacts with length-independent similarity scoring using diffxlen()
- Maintain compatibility with legacy systems using older TLSH hash formats via oldhash()

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Generates locality-sensitive hashes for fuzzy matching of binary data, allowing similarity comparison of objects by hash value rather than exact matching.

Yes, if you need fuzzy matching on binary data and can tolerate C++ compilation at install time. The package is actively maintained, permissively licensed, has no known vulnerabilities, and solves a specific problem well. The high install friction is the main trade-off—ensure your deployment environment has build tools available before adopting it.

## Install

pip install py-tlsh
uv add py-tlsh
poetry add py-tlsh

## Installing py-tlsh

Before you install: High install friction due to C++ extension compilation required. Package is actively maintained with recent commits and no known vulnerabilities, but the compiled dependency means build tools and headers must be present on the target system.

License in practice: Licensed under Apache or BSD (permissive), so commercial and proprietary use is permitted without restriction or copyleft obligation.

Quickstart:

import tlsh

# Hash binary data (minimum 50 bytes recommended)
h1 = tlsh.hash(data)
h2 = tlsh.hash(similar_data)

# Compare hashes for similarity
score = tlsh.diff(h1, h2)

Data must be bytes (not string), and minimum 50 bytes with sufficient complexity required for hash generation; C++ extension compilation needed at install time.

Verify before relying:

- Whether the C++ extension builds reliably on all major platforms despite the 'OS Independent' classifier
- Performance characteristics and hash collision rates for real-world binary data
- Whether the memory leak fixes in 4.12.1 fully resolved the reported issues

## Package facts

- License: Apache or BSD (permissive)
- Python support: supports_current
- Install friction: high
- Maintenance: active
- Downloads: 102.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

fuzzy matching binary data, locality sensitive hashing, similarity detection hash, tlsh hash algorithm, binary data fingerprinting, similar object detection, hash-based similarity comparison, fuzzy-matching, binary-hashing, c-extension

[View on SkillFed](https://skillfed.io/packages/py-tlsh) · [View on PyPI](https://pypi.org/project/py-tlsh/)