Install & Compatibility
Where this runs
tested against v17.0.1 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.000s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
unicodedata2
✓ import unicodedata2
✗ import unicodedata
To use the updated Unicode database provided by this library, you must explicitly import `unicodedata2`. Importing `unicodedata` will use the standard library's built-in module, which is tied to your Python version's Unicode data, not `unicodedata2`'s.
This quickstart demonstrates how to import `unicodedata2` and use its core functions like `name()`, `category()`, and `normalize()` to inspect and process Unicode characters and strings. It highlights character properties and the importance of normalization for string comparison.
import unicodedata2
# Get character name
char = 'é'
name = unicodedata2.name(char)
print(f"Character: '{char}', Name: {name}")
# Get character category
category = unicodedata2.category(char)
print(f"Category for '{char}': {category}")
# Normalize a Unicode string
s1 = 'café'
s2 = 'cafe\u0301' # 'e' followed by combining acute accent
print(f"String 1: '{s1}', String 2: '{s2}'")
print(f"Are they equal? {s1 == s2}")
normalized_s1 = unicodedata2.normalize('NFC', s1)
normalized_s2 = unicodedata2.normalize('NFC', s2)
print(f"Normalized S1 (NFC): '{normalized_s1}'")
print(f"Normalized S2 (NFC): '{normalized_s2}'")
print(f"Are they equal after NFC? {normalized_s1 == normalized_s2}")
Debug
Known issues
breakingMajor version updates (e.g., 17.0.0, 16.0.0) correspond to new Unicode Standard releases. Code relying on specific character properties or the existence of certain characters might behave differently or break with new Unicode versions due to additions, changes, or deprecations in the standard.fixReview your code after upgrading `unicodedata2` for any logic dependent on precise Unicode character data. Test thoroughly against the new Unicode version to ensure compatibility.
affects: All major version increments (e.g., 16.x.x to 17.x.x)
breakingSupport for End-of-Life (EOL) Python versions is periodically dropped. For example, version 14.0.0 dropped support for Python 2.7 and 3.5, and older versions removed support for Python 3.3 and 3.4.fixEnsure your project runs on a currently supported Python version before upgrading `unicodedata2`. Check the library's release notes for specific Python version compatibility with each `unicodedata2` release.
affects: 14.0.0 and later (for Python 2.7, 3.5). Other versions for earlier EOL Python versions.
gotchaThe `unicodedata2` library does not automatically replace the standard library's `unicodedata` module. You must explicitly `import unicodedata2` to access the updated Unicode character database. If you `import unicodedata`, you will use the older, built-in data tied to your Python interpreter's version.fixAlways use `import unicodedata2` in your code if you intend to leverage the more recent Unicode data. Some projects use `try...except ImportError: import unicodedata2 as unicodedata` as a fallback mechanism.
affects: All versions
gotchaNew Python versions might initially encounter build issues with `unicodedata2` until the library releases an update. For instance, there were initial problems building `unicodedata2` with Python 3.11 that were later resolved in version 15.0.0.fixIf encountering build errors with a newly released Python version, check the `unicodedata2` GitHub issues or release notes for patches. Consider pinning `unicodedata2` to an older version or using a slightly older Python patch release until an update is available.
affects: New Python minor versions upon their initial release (e.g., Python 3.11 prior to `unicodedata2` v15.0.0).
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'unicodedata2'
The `unicodedata2` package has not been installed in your current Python environment.
fixInstall the package using pip: `pip install unicodedata2`
ValueError: no such result
You are likely using the standard library's `unicodedata` module, which is tied to an older Unicode version, to query characters or properties introduced in newer Unicode versions.
fixInstall `unicodedata2` (`pip install unicodedata2`) and then replace `import unicodedata` with `import unicodedata2 as unicodedata` to use the updated Unicode database.
ModuleNotFoundError: No module named 'unicodedata2.unicodedata'
You are attempting to import a non-existent submodule named 'unicodedata' from the `unicodedata2` package.
fix`unicodedata2` is designed to be imported directly as the main module: `import unicodedata2` or `import unicodedata2 as unicodedata`.
Upgrade
Version history
17.0.1latest on PyPI · released Feb 12, 2026
Audit
Dependencies
No dependency data recorded yet.