Install & Compatibility
Where this runs
tested against v2.7.4 · 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
py 3.10
✕ build_error
✕ build_error
py 3.11
✕ build_error
✕ build_error
py 3.12
✕ build_error
✕ build_error
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✓ 3.4s
58MB installed
● package 58MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
icu
✓ import icu
All functionalities are exposed through the top-level `icu` module.
Locale
✓ from icu import Locale
Collator
✓ from icu import Collator
BreakIterator
✓ from icu import BreakIterator
This quickstart demonstrates basic locale creation, retrieving locale display names, and using a `Collator` for locale-aware string sorting, which is a common use case for ICU.
import icu
# Get the default locale
default_locale = icu.Locale.getDefault()
print(f"Default Locale: {default_locale.getDisplayName()}")
# Create a specific locale and get its display name in the default locale
japanese_locale = icu.Locale("ja_JP")
print(f"Japanese Locale Display Name: {japanese_locale.getDisplayName(default_locale)}")
# Perform collation (sorting) using a specific locale
collator = icu.Collator.createInstance(japanese_locale)
words = ["りんご", "みかん", "バナナ"]
sorted_words = sorted(words, key=collator.getSortKey)
print(f"Sorted Japanese words: {sorted_words}")
Debug
Known issues
gotchaInstalling PyICU (the base project) from source without `pyicu-binary` can be challenging, requiring a system-wide ICU C++ library installation and correct environment variables (`PKG_CONFIG_PATH`, `ICU_VERSION`, `CC`/`CXX`). `pyicu-binary` aims to circumvent this by providing pre-built wheels.fixPrefer `pip install pyicu-binary` if a wheel is available for your platform and Python version. If building from source or using the regular `pyicu` package, ensure `pkg-config` is installed and can locate your ICU installation, and set necessary environment variables as detailed in the PyICU documentation.
affects: All versions of PyICU when building from source.
breakingThe `icu-config` utility has been deprecated since ICU 63.1. Build systems for PyICU now rely on `pkg-config` to locate ICU libraries and headers.fixEnsure `pkg-config` is installed and properly configured to find your ICU installation. If encountering build issues related to `icu-config`, update your system's ICU development packages or explicitly configure `PKG_CONFIG_PATH`.
affects: PyICU versions built with ICU 63.1 or newer.
gotchaWhen interfacing directly with PyICU's C++-like APIs, be mindful of Python native strings versus `icu.UnicodeString`. While Python 3 handles Unicode natively, certain PyICU methods might modify `icu.UnicodeString` objects in-place or expect them for specific behaviors, leading to unexpected results if a native Python string is used.fixFor operations where in-place modification or direct ICU object interaction is expected, explicitly convert Python strings to `icu.UnicodeString` (e.g., `icu.UnicodeString('your string')`). Refer to the PyICU examples and ICU C++ documentation for API specifics. affects: All versions
breakingICU C++ APIs use a `UErrorCode` reference argument for error reporting, which PyICU wraps by omitting this argument and raising Python exceptions (e.g., `icu.ICUError`) instead. Code expecting C++-style error handling will break.fixAdopt Pythonic `try-except icu.ICUError` blocks for error handling instead of checking `UErrorCode` values.
affects: All versions
Upgrade
Version history
2.7.4latest on PyPI · released Sep 14, 2021
Audit
Dependencies
ICU C++ LibraryoptionalPyICU is a wrapper around the native ICU C++ library. While 'pyicu-binary' often bundles the necessary ICU components within its wheels, a system-wide ICU installation (e.g., `libicu-dev` on Debian/Ubuntu, `icu4c` via Homebrew) is required if a pre-built wheel is not available for your specific platform/Python version, or when building PyICU from source.