Install & Compatibility
Where this runs
tested against v0.22.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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.041s · 33.7MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.5s · import 0.033s · 30MB
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
fuzz
✓ from thefuzz import fuzz
process
✓ from thefuzz import process
fuzzywuzzy
✓ from thefuzz import fuzz, process
✗ from fuzzywuzzy import fuzz, process
The original 'fuzzywuzzy' library has been renamed and is now 'thefuzz'. Old imports will fail.
This example demonstrates basic ratio calculation between two strings and how to find the best (or top N) matches for a query string within a list of choices using `fuzz` and `process` modules.
from thefuzz import fuzz
from thefuzz import process
# Basic string comparison
score = fuzz.ratio("this is a test", "this is a test!")
print(f"Ratio score: {score}")
# Find the best match in a list
choices = ["apple pie", "grapefruit", "apple tree"]
query = "apple"
best_match, best_score = process.extractOne(query, choices)
print(f"Best match for '{query}': '{best_match}' with score {best_score}")
# Get top N matches
top_matches = process.extract(query, choices, limit=2)
print(f"Top matches for '{query}': {top_matches}")
Debug
Known issues
breakingThe library was renamed from `fuzzywuzzy` to `thefuzz`. Direct imports of `fuzzywuzzy` will no longer work, and `python-Levenshtein` is now an optional dependency.fixUpdate all `fuzzywuzzy` imports to `thefuzz`. Install `python-Levenshtein` explicitly for performance: `pip install thefuzz[speedup]`.
affects: < 0.20.0 (fuzzywuzzy) to >= 0.20.0 (thefuzz)
gotchaPerformance degrades significantly without the optional `python-Levenshtein` dependency (often referred to as 'speedup'). The library falls back to a pure Python implementation which is much slower.fixAlways install `thefuzz` with the speedup extras: `pip install thefuzz[speedup]`. Ensure `python-Levenshtein` is successfully installed and not just `thefuzz` by itself.
affects: All versions of `thefuzz`
gotchaThe `process.extract` and `process.extractOne` functions return tuples, where the first element is the matched string and the second is the score. Be careful when destructuring the results.fixWhen using `extractOne`, assign to two variables: `matched_string, score = process.extractOne(...)`. When using `extract`, iterate over the list of tuples: `for item, score in process.extract(...)`.
affects: All versions of `thefuzz`
gotchaDifferent ratio functions (`fuzz.ratio`, `fuzz.partial_ratio`, `fuzz.token_sort_ratio`, `fuzz.token_set_ratio`) are suited for different scenarios. Using the wrong one can lead to unintuitive results.fixUnderstand the differences: `ratio` is for exact order, `partial_ratio` for substrings, `token_sort_ratio` for reordered words, and `token_set_ratio` for missing/extra words. Choose based on your specific string comparison needs.
affects: All versions of `thefuzz`
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'fuzzywuzzy'
Users often confuse `fuzzywuzzy` (the unmaintained predecessor) with `thefuzz` (the actively maintained fork), leading to an import error when old code attempts to import `fuzzywuzzy` but it's not installed.
fixInstall `thefuzz` using `pip install thefuzz` and update your import statements from `from fuzzywuzzy import fuzz, process` to `from thefuzz import fuzz, process`.
error: command 'gcc' failed with exit status 1
This error occurs during installation of `python-Levenshtein` (an optional dependency for `thefuzz` speedups) because the required C compiler (like GCC) is not installed or not found in the system's PATH.
fixInstall the required C build tools for your operating system (e.g., `sudo apt-get install build-essential` on Linux, Xcode Command Line Tools on macOS, or Visual C++ Build Tools on Windows) or proceed knowing `thefuzz` will fall back to a slower pure Python implementation without `python-Levenshtein`.
TypeError: sequence item 0: expected str instance, NoneType found
`thefuzz` functions like `fuzz.ratio` or `fuzz.partial_ratio` expect string arguments, and this error occurs when non-string types (such as `None` or integers) are passed as input.
fixEnsure all inputs to `thefuzz` functions are strings; convert non-string data types to strings using `str()` before passing them.
AttributeError: module 'thefuzz' has no attribute 'ratio'
The `ratio` function, along with other fuzzy matching functions, resides within the `fuzz` submodule of the `thefuzz` package, not directly under the top-level `thefuzz` package.
fixImport `fuzz` explicitly from `thefuzz` using `from thefuzz import fuzz` before calling `fuzz.ratio` (or `fuzz.partial_ratio`, etc.).
Upgrade
Version history
0.22.1latest on PyPI · released Jan 19, 2024
Audit
Dependencies
python-LevenshteinoptionalProvides C-level speedups for string comparison algorithms. Highly recommended for performance-critical applications.