pyunormalize

library17.0.0pypypi✓ verified 26d ago

pyunormalize is a pure-Python library for Unicode normalization (NFC, NFD, NFKC, NFKD) that operates independently of Python's built-in Unicode database. It uses its own dedicated data, ensuring strict conformance to the latest Unicode Standard (currently v17.0.0). New major versions are typically released to align with updates to the Unicode Standard.

serialization

pip install pyunormalize

github ↗package ↗

INSTALL

IMPORT

SIG · PYUNORMALIZE

pyunormalize

serializationpythonv17.0.0

Install

1.6s avg

Import

19107ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v17.0.0 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 17.006s · 18.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 21.208s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

NFC

✓ from pyunormalize import NFC

NFD

✓ from pyunormalize import NFD

NFKC

✓ from pyunormalize import NFKC

NFKD

✓ from pyunormalize import NFKD

UCD_VERSION

✓ from pyunormalize import UCD_VERSION

✗ import pyunormalize; pyunormalize.UCD_VERSION

UCD_VERSION is a direct export for convenience.

normalize (general function)

✓ from pyunormalize import NFC, NFD, NFKC, NFKD

✗ import unicodedata; unicodedata.normalize('NFC', text)

pyunormalize is designed to be independent of Python's built-in `unicodedata` module and its potentially older Unicode database. Use the specific NFC/NFD/NFKC/NFKD functions from pyunormalize.

This example demonstrates how to import and use the four primary Unicode normalization forms (NFC, NFD, NFKC, NFKD) provided by pyunormalize, and how to retrieve the Unicode Character Database (UCD) version in use.

from pyunormalize import NFC, NFD, NFKC, NFKD, UCD_VERSION # Example string with accented characters text = "élève" # Normalize to different forms nfc_text = NFC(text) nfd_text = NFD(text) nfkc_text = NFKC(text) nfkd_text = NFKD(text) print(f"Original: {text}") print(f"NFC: {nfc_text}") print(f"NFD: {nfd_text}") print(f"NFKC: {nfkc_text}") print(f"NFKD: {nfkd_text}") print(f"Unicode database version: {UCD_VERSION}")

Debug

Known issues

breakingVersion 17.0.0 dropped official support for Python 3.6 and 3.7. Users on these Python versions should upgrade to Python 3.8 or newer, or stick to an older version of pyunormalize (e.g., < 17.0.0).

fix

Upgrade Python environment to 3.8+ or pin `pyunormalize<17.0.0`.

affects: 17.0.0+

gotchapyunormalize is designed to use its own Unicode Character Database (UCD), making it independent of the UCD version bundled with your Python interpreter's `unicodedata` module. This is its core feature, but users migrating from `unicodedata` should be aware that results might differ if their Python's `unicodedata` is significantly older or newer than pyunormalize's UCD version.

fix

Understand that `pyunormalize` provides strict, self-contained Unicode version support. Use `pyunormalize.UCD_VERSION` to verify the active Unicode version.

affects: All

gotchaWhile pyunormalize correctly implements Unicode normalization, be aware of broader security implications of Unicode equivalence. Characters that appear identical after normalization (e.g., compatibility equivalences in NFKC/NFKD) can be represented by different underlying code points, which might be exploited in security contexts (e.g., path traversal, input validation, string comparisons in authentication).

fix

Thoroughly validate and sanitize all user inputs. Do not rely solely on normalization for security checks; consider canonical forms (NFC, NFD) for strict equivalence if possible, and be mindful of compatibility equivalences (NFKC, NFKD) if they are used in security-sensitive comparisons.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pyunormalize'

The pyunormalize package has not been installed in your current Python environment.

fix

pip install pyunormalize

AttributeError: module 'pyunormalize' has no attribute 'normalize'

The main normalization function in `pyunormalize` is named `unormalize`, not `normalize` as it is in the standard `unicodedata` module.

fix

from pyunormalize import unormalize; unormalize('text', 'NFC')

ValueError: form must be one of 'NFC', 'NFD', 'NFKC', 'NFKD'

The normalization form provided to `unormalize` is invalid or not recognized, expecting one of the specified string constants or their corresponding imported `pyunormalize` constants.

fix

from pyunormalize import unormalize, NFC; unormalize('text', 'NFC') # or unormalize('text', NFC)

TypeError: text must be a string

The `unormalize` function received an input for its `text` argument that was not a string.

fix

Ensure the input `text` is a Python string (`str`) before passing it to `unormalize`, e.g., `unormalize(str(non_string_data), 'NFC')`.

Upgrade

Version history

17.0.0latest on PyPI · released Sep 28, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/mlodewijck/pyunormalize ↗

packagehttps://pypi.org/project/pyunormalize/ ↗