Jaro-Winkler String Similarity

2.0.3 · active · verified Sun Apr 12

The `jaro-winkler` library provides Python implementations of the Jaro and Jaro-Winkler string similarity metrics. It allows for comparison of two strings, returning a score from 0 (no match) to 1 (perfect match). The current version is 2.0.3, offering standard and customizable versions of the functions. While not explicitly stated, the project's release cadence appears to be moderate, with major updates occurring over several years.

Warnings

gotcha There are two distinct Python packages with very similar names: `jaro-winkler` (this library, which imports as `jaro`) and `jarowinkler` (a different, often faster implementation by maxbachmann, which imports as `jarowinkler`). Users often confuse them, leading to `ModuleNotFoundError` or unexpected behavior if `pip install` one but `import` the other.
Fix: Ensure you `pip install jaro-winkler` if you intend to `import jaro`, or `pip install jarowinkler` if you intend to `import jarowinkler`. Do not mix imports from the two different packages.
gotcha The Jaro-Winkler algorithm, by design, gives a higher weight to matching prefixes. This means strings with a common beginning will naturally score higher, even if other parts of the strings are very different. This behavior is usually desirable for name matching but can be unexpected in other contexts.
Fix: Be aware of the prefix bias when interpreting similarity scores. If this bias is undesirable, consider alternative string similarity algorithms like Levenshtein distance which treats all character positions equally.
gotcha While often referred to as a distance metric, the Jaro-Winkler 'distance' (1 - similarity) does not strictly adhere to the mathematical definition of a metric because it may not satisfy the triangle inequality.
Fix: This is a theoretical characteristic; for most practical applications, it does not pose a problem. However, if you are building systems that rely on strict metric properties (e.g., in graph theory or certain clustering algorithms), you should be aware of this limitation.
gotcha For optimal performance, especially when dealing with very large datasets or requiring integration with tools like RapidFuzz, the `jarowinkler` (no hyphen) package by maxbachmann (which implements the RapidFuzz C-API) may offer significantly faster computation compared to this `jaro-winkler` library.
Fix: Evaluate both `jaro-winkler` and `jarowinkler` if performance is critical. The `jarowinkler` library explicitly leverages C-API and bitparallelism for speed.

Install

pip install jaro-winkler Install stable version

Imports

jaro_winkler_metric
```
from jaro import jaro_winkler_metric
```
The `jaro-winkler` package (with a hyphen) installs a module named `jaro`. There is a separate, similarly named package `jarowinkler` (no hyphen) that provides a `jarowinkler` module and `jaro_winkler_similarity` function. Importing from the wrong module is a common mistake.
jaro_metric
```
from jaro import jaro_metric
```
Imports the standard Jaro string metric.
original_metric
```
from jaro import original_metric
```
Imports the Jaro metric matching the reference C code, including typo tables and longer string adjustments.

Quickstart

This quickstart demonstrates how to import the `jaro` module and use its `jaro_winkler_metric` and `jaro_metric` functions to calculate string similarity scores. Scores range from 0 (no similarity) to 1 (identical).

import jaro

# Calculate Jaro-Winkler similarity
score_winkler = jaro.jaro_winkler_metric('SHACKLEFORD', 'SHACKELFORD')
print(f"Jaro-Winkler Similarity: {score_winkler}")

# Calculate Jaro similarity
score_jaro = jaro.jaro_metric('MARTHA', 'MARHTA')
print(f"Jaro Similarity: {score_jaro}")

view raw JSON →