Understanding and Using Fuzzy String Matching with Python’s FuzzyWuzzy Library: An In-Depth Guide to process.extractOne

When dealing with textual data, finding exact matches between strings is often straightforward. However, real-world data is often messy, and exact string matching might not be suitable for all cases. Fuzzy string matching is a technique used to find approximate matches between strings, even when they are not exactly the same. In this article, we will explore the Python library FuzzyWuzzy and its process.extractOne function, which allows you to find the closest match to a given string from a list of strings using fuzzy string matching.

1. Introduction to Fuzzy String Matching

Fuzzy string matching, also known as approximate string matching, is a technique used to find strings that are approximately equal to a given pattern. Unlike exact string matching, which requires strings to be identical, fuzzy string matching allows for differences such as typos, variations in spelling, or slight changes in word order. It is often used in tasks such as data cleaning, record linkage, and information retrieval.

2. The FuzzyWuzzy Library

FuzzyWuzzy is a popular Python library for fuzzy string matching. It uses the Levenshtein distance to measure the similarity between two strings. The library provides various functions to compare strings and find the best match from a list of strings.

To install the FuzzyWuzzy library, you can use the following pip command:

pip install fuzzywuzzy[speedup]

The [speedup] option installs the optional python-Levenshtein package, which speeds up the string comparison operations.

3. The process.extractOne Function

The process.extractOne function is a utility provided by the FuzzyWuzzy library that takes a query string and a list of strings as input and returns the closest match from the list based on the calculated similarity score. The similarity score ranges from 0 (completely different) to 100 (identical).

To use the process.extractOne function, first, import the FuzzyWuzzy library:

from fuzzywuzzy import process

Next, prepare your query string and the list of strings you want to search for the best match. For example:

query = "apple"
choices = ["apples", "banana", "grape", "orange", "peach"]

Now, use the process.extractOne function to find the best match:

best_match = process.extractOne(query, choices)

This code will output:

('apples', 91)

The result is a tuple containing the best match (“apples”) and its similarity score (91) in this example.

4. Customizing the Scoring Function

FuzzyWuzzy provides several scoring functions, such as:

  • ratio: The default scoring function, which calculates the Levenshtein distance between the query and each choice.
  • partial_ratio: A scoring function that calculates the Levenshtein distance between the query and the best matching substring of each choice.
  • token_sort_ratio
  • token_sort_ratio: A scoring function that tokenizes the strings, sorts the tokens alphabetically, and then calculates the Levenshtein distance between the sorted token strings.
  • token_set_ratio: A scoring function that tokenizes the strings and calculates the Levenshtein distance between sets of unique tokens, considering their common and unique elements.

You can specify a custom scoring function when using the process.extractOne function by passing it as the scorer argument. First, import the desired scoring function from the fuzzywuzzy.fuzz module:

from fuzzywuzzy import fuzz

Then, pass the scoring function to the process.extractOne function:

query = "apple"
choices = ["apples", "banana", "grape", "orange", "peach"]

best_match = process.extractOne(query, choices, scorer=fuzz.token_sort_ratio)

Using the token_sort_ratio scorer in this example, the output will be:

('apples', 100)

The similarity score is now 100, as the token_sort_ratio scorer considers the tokenized and sorted strings, which are identical in this case.

5. Setting a Score Cutoff

You can set a minimum score threshold for the process.extractOne function using the score_cutoff argument. If no choice meets the minimum score, the function will return None. For example:

query = "apple"
choices = ["banana", "grape", "orange", "peach"]

best_match = process.extractOne(query, choices, score_cutoff=80)

Since none of the choices have a similarity score greater than or equal to 80, the output will be:


6. Real-World Applications of process.extractOne

The process.extractOne function is useful in various real-world scenarios, including:

  • Data cleaning: Identifying and correcting typos, misspellings, or inconsistent naming conventions in datasets.
  • Record linkage: Matching records from different databases or sources based on similar text fields, such as names or addresses.
  • Information retrieval: Finding relevant documents or entries in a database based on user queries, even when the query contains errors or does not exactly match the stored text.
  • Autocomplete: Suggesting possible completions for partially typed words or phrases in search boxes or text input fields.


Examples can be found at fuzzywuzzy.process.extractOne


In this article, we have explored the process of fuzzy string matching using the FuzzyWuzzy library and its process.extractOne function. This powerful tool enables you to find the best match from a list of strings based on their similarity, even when the strings are not exactly identical. By understanding and utilizing this technique, you can improve your data processing, record linkage, and information retrieval tasks, making your Python applications more robust and user-friendly.

Leave a Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.