Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Using Python RapidFuzz extract and extractOne for Fuzzy Matching

Using RapidFuzz extract and extractOne in Python: understand return values, limit and score_cutoff, scorer choice, and common pitfalls.

~4 min readPython
#fuzzy matching#RapidFuzz#string similarity#Python
A Python code snippet showing RapidFuzz extract and extractOne functions comparing strings with similarity scores.

When you need to find the closest matching string from a list of candidates in Python, RapidFuzz's extract and extractOne functions are the core entry points. These functions from the rapidfuzz.process module let you compare a query against a collection of choices and return ranked matches with similarity scores.

What extract and extractOne Do in RapidFuzz

rapidfuzz.process.extract and rapidfuzz.process.extractOne are the two primary functions for comparing a query string against a collection of candidate strings. They both use a scorer (by default fuzz.ratio) to compute similarity scores and return the best matches.

The key difference is the shape of the result. extractOne returns the highest-scoring match as a tuple (choice, score, index), or None if a score_cutoff is set and no match reaches it. extract returns a list of such tuples, sorted by score in descending order, and lets you control how many results to return with the limit parameter.

Both functions accept the same core arguments: query, choices, scorer, processor, and score_cutoff. The processor argument applies a callable to both the query and each choice before scoring, which is useful for normalization like lowercasing or stripping whitespace.

extractOne: When You Need a Single Best Match

Use extractOne when you only care about the closest match. For example, matching a user-typed product name against a catalog and returning the canonical name.

python
from rapidfuzz import process, fuzz catalog = ['Wireless Mouse', 'USB-C Cable', 'Mechanical Keyboard'] query = 'wireless mous' best = process.extractOne(query, catalog, scorer=fuzz.WRatio) choice, score, index = best print(choice, score, index)

Here fuzz.WRatio is case-insensitive and handles partial matches well. The returned result contains the matched choice, the similarity score, and the index in the original list.

If you pass score_cutoff and no candidate reaches it, extractOne returns None. You can use this to avoid weak matches:

python
best = process.extractOne(query, catalog, scorer=fuzz.ratio, score_cutoff=80) if best: print(best) else: print('No match reached 80')

Because extractOne only needs the top result, it can return early when it finds a perfect score. This can make it faster than extract for large candidate sets, depending on the data.

extract: Getting Multiple Matches with Scores

When you need a ranked list of plausible matches—for example, showing autocomplete suggestions—use extract. It returns a list of tuples, each with the same structure as extractOne's result.

python
from rapidfuzz import process, fuzz choices = ['apple pie', 'apple juice', 'banana bread', 'apple cider'] query = 'apple' matches = process.extract(query, choices, scorer=fuzz.partial_ratio, limit=3) for choice, score, index in matches: print(f'{choice}: {score}')

The limit parameter caps the number of returned matches. If omitted, extract returns the top 5 matches by default; pass a larger limit to get more. You can also filter with score_cutoff to exclude low-scoring entries.

Choosing the Right Scorer for Your Data

The scorer determines how similarity is measured. RapidFuzz provides several, each suited to different data shapes:

  • fuzz.ratio – standard Levenshtein-based similarity, case-sensitive at the scorer level.
  • fuzz.partial_ratio – best matching substring, good for long strings with common prefixes.
  • fuzz.token_sort_ratio – sorts tokens before comparing, useful for reordered words.
  • fuzz.token_set_ratio – ignores duplicate tokens and compares sets, robust for extra words.

For example, matching 'New York' against 'York New' would score low with ratio but high with token_sort_ratio. Choose the scorer based on the expected variation in your data.

Using limit and score_cutoff to Control Results

Both extract and extractOne accept score_cutoff. For extract, limit is also available. These parameters let you balance recall and precision.

python
matches = process.extract( query, choices, scorer=fuzz.ratio, limit=5, score_cutoff=70 )

Setting limit to a small number reduces the size of the returned list, which matters when choices contains thousands of entries. score_cutoff avoids returning irrelevant matches, so you don't have to filter the result afterward.

For extractOne, score_cutoff is the main filter. If you want to enforce a minimum similarity, pass it explicitly; otherwise, the function returns the best match even if its score is low.

Performance and Memory Behavior of extract vs extractOne

RapidFuzz is implemented in C++ and uses optimized algorithms, so these functions can be much faster than pure-Python alternatives like fuzzywuzzy. However, the choice between extract and extractOne affects runtime.

extractOne can terminate early when it finds a perfect score (100) because no later candidate can score higher. This can make it more efficient for large candidate lists when you only need the top match.

extract with a limit still has to score all candidates to produce a sorted list, unless the scorer supports early termination internally. For very large datasets, consider pre-filtering choices with a cheaper metric (e.g., length difference) before running extract.

Memory usage is proportional to the number of returned matches. With limit set, extract only allocates for that many results. If you use limit=None, it stores scores for every choice, which can be significant for millions of entries.

Common Mistakes and How to Avoid Them

One frequent mistake is forgetting that extractOne returns None when no match reaches the score_cutoff you passed. Always check for None before unpacking.

Another is assuming that fuzz.ratio normalizes case on its own. If you call fuzz.ratio('Apple', 'apple') directly, it is case-sensitive. In process.extractOne, however, the default processor lowercases and strips whitespace, so 'Apple' and 'apple' usually match. Pass processor=None to disable that built-in preprocessing, or pass a custom processor to control normalization.

python
process.extractOne(query, choices, processor=lambda s: s.lower())

Also, remember that the processor is applied to both the query and the choices. If you pass a processor that expects a string, ensure your choices are strings. Passing None disables preprocessing.

Finally, extract returns references to the original choice objects, not copies. Mutating a returned object will affect the corresponding object in choices, and replacing an item in choices after the call will not change an already returned reference.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.