fuzzysearch

library0.8.1pypypi✓ verified 23d ago

Fuzzysearch is a Python library for finding approximate subsequence matches within long texts or data. It uses Levenshtein distance with configurable parameters to efficiently locate patterns even with typos or minor variations. The library is highly optimized, offering C and Cython extensions for performance while providing pure-Python fallbacks. It is currently at version 0.8.1.

data

pip install fuzzysearch

github ↗package ↗

INSTALL

IMPORT

SIG · FUZZYSEARCH

fuzzysearch

datapythonv0.8.1

Install

2.0s avg

Import

86ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.8.1 · pip install

no network on importno background threads

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

installs and imports cleanly · install 0.0s · import 0.092s · 18.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.0s · import 0.080s · 19MB

17MB installed

● package 17MB

Code

Verified usage

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

find_near_matches

✓ from fuzzysearch import find_near_matches

The primary function for in-memory fuzzy searching.

find_near_matches_in_file

✓ from fuzzysearch import find_near_matches_in_file

Used for searching within file-like objects (e.g., binary files).

This example demonstrates how to find approximate matches of a subsequence ('PATTERN') within a larger string, allowing for a maximum Levenshtein distance of 1.

from fuzzysearch import find_near_matches # Search for 'PATTERN' with a maximum Levenshtein Distance of 1 matches = find_near_matches('PATTERN', '---PATERN---', max_l_dist=1) for match in matches: print(f"Found match: '{match.matched}' at index {match.start}-{match.end} with distance {match.dist}")

Debug

Known issues

breakingSupport for older Python versions has been dropped. As of version 0.8.1, fuzzysearch officially supports Python 3.8+ and PyPy 3.9 and 3.10. Older versions (e.g., Python 2.x, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7) are no longer supported.

fix

Upgrade to a supported Python version (3.8+).

affects: <=0.7.3

gotchaThis library is designed for fuzzy *search* (finding approximate *subsequences* within longer texts/data) rather than fuzzy *comparison* of two strings. If you need to compare two strings for similarity (e.g., 'apple' vs 'aple'), consider libraries like FuzzyWuzzy or RapidFuzz.

fix

Understand the library's primary use case. For string comparison, use dedicated fuzzy matching libraries.

affects: All

gotchaOlder versions (prior to 0.7.3) could experience segmentation faults or undefined behavior due to incorrect handling of bytes-like inputs in C extensions. While fixed, this highlights the importance of providing correct input types and updating.

fix

Ensure you are on version 0.7.3 or newer. Always provide appropriate string or bytes-like inputs as expected by the functions.

affects: <0.7.3

gotchaThe `find_near_matches` function is quite permissive by default, potentially matching unexpected characters (spaces, symbols, numbers) if not constrained. This can lead to false positives when searching for specific words or patterns.

fix

Pre-process your input strings (e.g., remove unwanted characters, normalize case) or use more specific matching parameters (e.g., `max_substitutions`, `max_deletions`, `max_insertions`) to control the match criteria more tightly.

affects: All

Errors

Common errors & fixes

ImportError: cannot import name find_near_matches

This error often occurs when a local Python file or directory is named 'fuzzysearch.py' or 'fuzzysearch', shadowing the installed `fuzzysearch` package and causing Python to import the local file instead of the library.

fix

Rename your local Python file or directory from 'fuzzysearch.py' or 'fuzzysearch' to something else (e.g., 'my_fuzzy_app.py') to avoid conflicting with the installed library's module name.

ValueError: # insertions must be limited!

The `fuzzysearch.find_near_matches` function requires at least one matching criterion (e.g., `max_l_dist`, `max_substitutions`, `max_deletions`, or `max_insertions`) to be specified, or a combination thereof. Calling it without any limits results in this error.

fix

Always provide a limit for at least one of the Levenshtein distance components. For example: `find_near_matches('pattern', 'sequence', max_l_dist=1)` or `find_near_matches('pattern', 'sequence', max_insertions=1, max_deletions=1)`.

ValueError: empty sequence

In previous versions of `fuzzysearch` (prior to 0.8.1), passing an empty sequence (or subsequence) to `find_near_matches` could sometimes lead to a ValueError.

fix

Ensure that both the `subsequence` and `sequence` arguments passed to `find_near_matches` are non-empty. If you are on an older version, upgrading to `fuzzysearch` 0.8.1 or newer also addresses this specific issue.

Upgrade

Version history

0.8.1latest on PyPI · released Nov 11, 2025

Audit

Dependencies

attrsrequiredUsed for `Match` objects and other data structures.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/taleinat/fuzzysearch ↗

packagehttps://pypi.org/project/fuzzysearch/ ↗