PyICU Binary

2.7.4 · active · verified Thu Apr 16

PyICU-binary (version 2.7.4) is a Python package that provides pre-built wheels for PyICU, a Python extension wrapping the ICU C++ API. ICU (International Components for Unicode) offers robust Unicode and internationalization services. This binary distribution aims to simplify installation by providing ready-to-use wheels for various platforms, bypassing the often complex process of compiling PyICU against a separately installed ICU library. While the upstream PyICU project sees regular updates, `pyicu-binary` releases track the upstream project as compatible binaries are built.

Common errors

```
FileNotFoundError: [Errno 2] No such file or directory: 'icu-config'
```
cause The `icu-config` command-line utility, previously used by PyICU's setup script to find ICU, is deprecated and often not present in modern ICU installations.

fix Ensure `pkg-config` is installed and available in your PATH. If installing PyICU from source, manually set `PKG_CONFIG_PATH` to point to your ICU installation's `pkgconfig` directory, or install `libicu-dev` (Debian/Ubuntu) or `icu4c` (Homebrew) which typically sets this up. Alternatively, use `pip install pyicu-binary`.
```
ImportError: libicui18n.so.XX: cannot open shared object file: No such file or directory
```
cause The Python interpreter cannot find the shared ICU C++ libraries at runtime. This often occurs when ICU is installed in a non-standard location or when environment variables specifying library paths are not set.

fix On Linux, ensure `LD_LIBRARY_PATH` includes the directory containing `libicui18n.so.XX`. On macOS, use `DYLD_LIBRARY_PATH`. On Windows, ensure the ICU DLLs are in your system `PATH`. For `pyicu-binary`, this usually implies a problem with the wheel's self-contained nature or a mismatch with the system's runtime environment. Reinstalling `pyicu-binary` or ensuring your system ICU is correctly linked might help.
```
RuntimeError: Please set the ICU_VERSION environment variable to the version of ICU you have installed.
```
cause The PyICU setup script could not automatically detect the installed ICU version and requires manual specification during the build process.

fix Before running `pip install pyicu` (for the source distribution, not `pyicu-binary`), set the `ICU_VERSION` environment variable to your ICU major version (e.g., `export ICU_VERSION=74`). This is typically avoided by using `pyicu-binary`.
```
AttributeError: module 'icu' has no attribute 'Collator' (or similar for other ICU classes)
```
cause This usually indicates a corrupted PyICU installation, an incompatible ICU C++ library version it was compiled against, or a mismatch where an older PyICU binary is being loaded with a newer Python/ICU environment.

fix Try reinstalling `pyicu-binary` (or `pyicu`) in a clean virtual environment. Ensure your system's ICU version (if applicable) is compatible with the PyICU version you are trying to use. If building from source, verify the C++ compiler and ICU version used during compilation.

Warnings

gotcha Installing 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.
Fix: Prefer `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.
breaking The `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.
Fix: Ensure `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`.
gotcha When 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.
Fix: For 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.
breaking ICU 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.
Fix: Adopt Pythonic `try-except icu.ICUError` blocks for error handling instead of checking `UErrorCode` values.

Install

pip install pyicu-binary Install latest binary wheel

Imports

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
```

Quickstart

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}")

view raw JSON →