{"id":1745,"library":"thefuzz","title":"thefuzz (Fuzzy String Matching)","description":"thefuzz is a Python library for fuzzy string matching, based on Levenshtein distance. It provides a simple API for comparing strings and extracting best matches from collections. The current version is 0.22.1, and it maintains an active development pace with periodic releases.","status":"active","version":"0.22.1","language":"python","source_language":"en","source_url":"https://github.com/seatgeek/thefuzz","tags":["string matching","fuzzy logic","levenshtein distance","nlp","data cleaning"],"install":[{"cmd":"pip install thefuzz","lang":"bash","label":"Base installation"},{"cmd":"pip install thefuzz[speedup]","lang":"bash","label":"With C-speedup (recommended)"}],"dependencies":[{"reason":"Provides C-level speedups for string comparison algorithms. Highly recommended for performance-critical applications.","package":"python-Levenshtein","optional":true}],"imports":[{"symbol":"fuzz","correct":"from thefuzz import fuzz"},{"symbol":"process","correct":"from thefuzz import process"},{"note":"The original 'fuzzywuzzy' library has been renamed and is now 'thefuzz'. Old imports will fail.","wrong":"from fuzzywuzzy import fuzz, process","symbol":"fuzzywuzzy","correct":"from thefuzz import fuzz, process"}],"quickstart":{"code":"from thefuzz import fuzz\nfrom thefuzz import process\n\n# Basic string comparison\nscore = fuzz.ratio(\"this is a test\", \"this is a test!\")\nprint(f\"Ratio score: {score}\")\n\n# Find the best match in a list\nchoices = [\"apple pie\", \"grapefruit\", \"apple tree\"]\nquery = \"apple\"\nbest_match, best_score = process.extractOne(query, choices)\nprint(f\"Best match for '{query}': '{best_match}' with score {best_score}\")\n\n# Get top N matches\ntop_matches = process.extract(query, choices, limit=2)\nprint(f\"Top matches for '{query}': {top_matches}\")","lang":"python","description":"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."},"warnings":[{"fix":"Update all `fuzzywuzzy` imports to `thefuzz`. Install `python-Levenshtein` explicitly for performance: `pip install thefuzz[speedup]`.","message":"The library was renamed from `fuzzywuzzy` to `thefuzz`. Direct imports of `fuzzywuzzy` will no longer work, and `python-Levenshtein` is now an optional dependency.","severity":"breaking","affected_versions":"< 0.20.0 (fuzzywuzzy) to >= 0.20.0 (thefuzz)"},{"fix":"Always install `thefuzz` with the speedup extras: `pip install thefuzz[speedup]`. Ensure `python-Levenshtein` is successfully installed and not just `thefuzz` by itself.","message":"Performance 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.","severity":"gotcha","affected_versions":"All versions of `thefuzz`"},{"fix":"When 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(...)`.","message":"The `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.","severity":"gotcha","affected_versions":"All versions of `thefuzz`"},{"fix":"Understand 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.","message":"Different 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.","severity":"gotcha","affected_versions":"All versions of `thefuzz`"}],"env_vars":null,"search_vec":"'0.22.1':36 'activ':41 'api':22 'base':14 'best':28 'clean':55 'collect':31 'compar':24 'current':33 'data':54 'develop':42 'distanc':17,52 'extract':27 'fuzzi':2,11,49 'levenshtein':16,51 'librari':9 'logic':50 'maintain':39 'match':4,13,29,48 'nlp':53 'pace':43 'period':45 'provid':19 'python':8 'releas':46 'simpl':21 'string':3,12,25,47 'thefuzz':1,5 'version':34","created_at":"2026-04-09T04:01:18.624926+00:00","updated_at":"2026-04-16T22:55:09.252480+00:00","problems":[{"fix":"Install `thefuzz` using `pip install thefuzz` and update your import statements from `from fuzzywuzzy import fuzz, process` to `from thefuzz import fuzz, process`.","cause":"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.","error":"ModuleNotFoundError: No module named 'fuzzywuzzy'"},{"fix":"Install 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`.","cause":"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.","error":"error: command 'gcc' failed with exit status 1"},{"fix":"Ensure all inputs to `thefuzz` functions are strings; convert non-string data types to strings using `str()` before passing them.","cause":"`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.","error":"TypeError: sequence item 0: expected str instance, NoneType found"},{"fix":"Import `fuzz` explicitly from `thefuzz` using `from thefuzz import fuzz` before calling `fuzz.ratio` (or `fuzz.partial_ratio`, etc.).","cause":"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.","error":"AttributeError: module 'thefuzz' has no attribute 'ratio'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.22.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/seatgeek/thefuzz","docs":null,"changelog":null,"pypi":"https://pypi.org/project/thefuzz/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":null}}