Install & Compatibility
Where this runs
tested against v4.6.3 · 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.182s · 18MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.3s · import 0.202s · 19MB
33MB installed
● package 33MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
levenshtein
✓ import textdistance
distance = textdistance.levenshtein.distance('text', 'test')
Most algorithms are exposed as attributes of the `textdistance` module, providing both `distance` and `similarity` methods directly. [2, 3]
JaroWinkler
✓ from textdistance import JaroWinkler
jw = JaroWinkler()
distance = jw.distance('martha', 'marhta')
Algorithms can also be imported as classes for custom initialization parameters, though direct attribute access is common for default settings. [3, 14]
This quickstart demonstrates how to use the `textdistance` library to calculate various similarity and distance metrics. It shows direct method calls on algorithm objects (e.g., `textdistance.levenshtein.distance`) and also a convenience function for Jaro-Winkler. [2, 3, 6, 7]
import textdistance
# Calculate Levenshtein distance
str1 = "kitten"
str2 = "sitting"
distance = textdistance.levenshtein.distance(str1, str2)
similarity = textdistance.levenshtein.similarity(str1, str2)
normalized_distance = textdistance.levenshtein.normalized_distance(str1, str2)
normalized_similarity = textdistance.levenshtein.normalized_similarity(str1, str2)
print(f"Strings: '{str1}', '{str2}'")
print(f"Levenshtein Distance: {distance}")
print(f"Levenshtein Similarity: {similarity}")
print(f"Levenshtein Normalized Distance: {normalized_distance:.2f}")
print(f"Levenshtein Normalized Similarity: {normalized_similarity:.2f}")
# Example with another algorithm (Jaro-Winkler)
str3 = "martha"
str4 = "marhta"
jaro_winkler_similarity = textdistance.jaro_winkler(str3, str4)
print(f"\nJaro-Winkler Similarity between '{str3}' and '{str4}': {jaro_winkler_similarity:.2f}")
textdistance --version
Debug
Known issues
breakingThe `abydos` library support was dropped in version 4.6.0. If your code relied on the `textdistance` integration with `abydos`, it will break.fixMigrate to `rapidfuzz` or other external libraries for performance, or use `textdistance`'s pure Python implementations.
affects: 4.6.0 and later
breakingPython 2 support was dropped in version 4.2.0. The library now explicitly supports Python 3.6+.fixUpgrade your Python environment to Python 3.6 or newer.
affects: 4.2.0 and later
gotchaFor optimal performance, especially in production environments, it is highly recommended to install `textdistance` with `[extras]` (e.g., `pip install textdistance[extras]`). Without these optional dependencies (like `rapidfuzz` and `numpy`), the pure Python implementations are significantly slower. [5, 7, 10]fixInstall with `pip install textdistance[extras]` to leverage faster C-based implementations from external libraries. The library automatically prioritizes faster external libraries if found. [4, 14]
affects: All versions where external libraries provide faster implementations
gotchaThe `Levenstein` algorithm was fixed in version 4.6.2 to ensure its return type is consistently `int`. If your application implicitly handled non-integer return values for Levenshtein distance prior to this version, its behavior might subtly change.fixVerify that your code correctly handles integer return types for Levenshtein distance calculations.
affects: 4.6.2 and later
gotchaBy default, `textdistance` may try to use external libraries (like `rapidfuzz`) if they are installed and provide faster implementations for a given algorithm. This behavior is controlled by an internal `libraries.json` file. If you need to explicitly control which implementation is used or troubleshoot performance, be aware of this mechanism and the `external` argument. [4, 14]fixIf you experience unexpected performance or behavior, inspect the `libraries.json` file in the `textdistance` package directory or use the `external=False` argument when instantiating an algorithm class to force pure Python implementation.
affects: All versions with external library support
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'textdistance'
The 'textdistance' library is not installed in your Python environment or the package name is misspelled.
fixInstall the library using pip: `pip install textdistance`
TypeError: 'Levenshtein' object is not callable
You are trying to call an instance of a textdistance algorithm class directly as a function, but it expects a specific method call like `.distance()` or `.similarity()`.
fixCall the appropriate method on the instance (e.g., `algo_instance.distance(s1, s2)`) or use the direct function provided by the library (e.g., `textdistance.levenshtein(s1, s2)`).
AttributeError: 'LCSstr' object has no attribute 'similarity'
Some textdistance algorithms, like LCSstr, only provide a `.distance()` method and do not implement a `.similarity()` method.
fixUse the `.distance()` method instead (e.g., `textdistance.LCSstr().distance(s1, s2)`) or choose an algorithm that explicitly supports a `.similarity()` method if that's what you need.
TypeError: distance() missing 1 required positional argument: 's2'
You called a textdistance algorithm's `.distance()` or `.similarity()` method with only one sequence, but it requires two sequences for comparison.
fixProvide both input sequences, for example: `textdistance.levenshtein.distance('hello', 'hallo')`. Upgrade
Version history
4.6.3latest on PyPI · released Jul 16, 2024
Audit
Dependencies
numpyoptionalOptional, used for optimized performance in some algorithms.
rapidfuzzoptionalOptional, provides faster implementations for several algorithms. Included with '[extras]'. [4, 5, 12]