pyicu

library2.16.2pypypi✓ verified 87d ago

PyICU is a Python extension that wraps the International Components for Unicode (ICU) C++ libraries. It provides robust, full-featured Unicode and globalization support for applications, handling tasks such as locale-aware text formatting, collation, character set conversions, and boundary analysis. The current version is 2.16.2, and the library maintains an active release cadence, often aligning with updates to the underlying ICU C++ library.

serialization

pip install pyicu

package ↗homepage ↗

INSTALL

IMPORT

SIG · PYICU

pyicu

serializationpythonv2.16.2

Install

—

Import

—

Disk

—

Pass rate

0/ 10

Env Coverage0 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v? · pip install

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.920 runs

build_error

glibc

py 3.10–3.920 runs

build_error

Code

Verified usage

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

Locale

✓ from icu import Locale

UnicodeString

✓ from icu import UnicodeString

BreakIterator

✓ from icu import BreakIterator

Collator

✓ from icu import Collator

This quickstart demonstrates how to create a `Locale` object to get a locale's display name and how to use `BreakIterator` for locale-aware text segmentation into grapheme clusters. PyICU exposes much of the underlying ICU C++ API directly.

import icu # Example 1: Locale-aware display name locale = icu.Locale('pt_BR') name = locale.getDisplayName() print(f"Locale display name: {name}") # Example 2: Text segmentation (grapheme clusters) text_to_segment = "café emoji 👨‍👩‍👧‍👦" breaker = icu.BreakIterator.createCharacterInstance(icu.Locale()) breaker.setText(text_to_segment) grapheme_clusters = [] i = 0 for j in breaker: grapheme_clusters.append(text_to_segment[i:j]) i = j print(f"Grapheme clusters for '{text_to_segment}': {grapheme_clusters}")

Debug

Known issues

gotchaPyICU requires the underlying ICU C++ libraries to be installed on your system. `pip install pyicu` will only install the Python bindings; it does not install the native ICU libraries. Installation paths (e.g., `LD_LIBRARY_PATH`, `DYLD_LIBRARY_PATH`, `PATH`) or `pkg-config` setup might be necessary.

fix

Ensure ICU C++ libraries are installed via your system's package manager (e.g., `brew install icu4c`, `sudo apt-get install libicu-dev`) and that `pkg-config` can locate them or relevant environment variables are set.

affects: All versions

gotchaPyICU's API closely mirrors the ICU4C C++ API, and there is no dedicated Python API documentation. Users must refer to the ICU4C C++ API documentation and translate patterns to Python.

fix

Consult the official ICU4C API reference (e.g., `https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/`) and infer the Python equivalents. Common patterns for string and date conversions are described in the PyICU README.

affects: All versions

gotchaHandling strings with PyICU can be nuanced due to the difference between ICU's mutable `UnicodeString` and Python's immutable `str` (or `unicode` in Python 2). ICU APIs may modify `UnicodeString` objects in place, while PyICU often overloads functions to accept Python `str` and convert to/from `UnicodeString` implicitly, assuming UTF-8 for `str` objects.

fix

Be aware of whether an ICU function expects an output `UnicodeString` to be modified in place or returns a new string. For non-UTF-8 encoded Python `str`, explicitly construct `UnicodeString(str, encodingName)`.

affects: All versions

breakingDepending on the version of the ICU C++ library you are building against, specific C++ standard compiler flags are required. ICU versions 60-74 require `-std=c++11`, while ICU 75 and later require `-std=c++17`. Failure to include the correct flag can lead to build errors.

fix

Ensure your CFLAGS include the appropriate C++ standard flag (`-std=c++11` or `-std=c++17`) when building PyICU from source, or use pre-built binaries if available for your environment.

affects: PyICU versions built against ICU 60+

deprecatedThe `icu-config` program for locating ICU libraries has been deprecated since ICU 63.1. `pkg-config` is now the recommended tool for this purpose.

fix

Ensure `pkg-config` is installed and configured to find your ICU libraries. Verify with `pkg-config --cflags --libs icu-i18n`.

affects: PyICU versions built against ICU 63.1+

Errors

Common errors & fixes

RuntimeError: Please install pkg-config on your system or set the ICU_VERSION environment variable to the version of ICU you have installed.

PyICU is a Python wrapper for the C++ ICU library, and its installation from source requires the `pkg-config` utility and the ICU C++ development libraries to be present and discoverable on your system for successful compilation.

fix

Install `pkg-config` and the ICU development libraries using your operating system's package manager (e.g., `sudo apt-get install libicu-dev pkg-config` on Debian/Ubuntu, or `brew install icu4c pkg-config` on macOS).

ModuleNotFoundError: No module named 'icu'

This error occurs when the Python interpreter cannot find the 'icu' module, which is provided by PyICU. This typically happens if PyICU was not installed correctly, the Python environment is corrupted, or the module's installation path is not in `sys.path`.

fix

Ensure PyICU is properly installed by running `pip install pyicu` in the active Python environment. If prior installation issues existed, verify that the underlying ICU C++ libraries were correctly installed before reinstalling PyICU.

ImportError: dlopen(...) Symbol not found: __ZNK6icu_XX... (or similar 'Symbol not found' errors during import)

This dynamic linker error indicates a mismatch between the version of the ICU C++ library PyICU was compiled against and the version of the ICU library available at runtime. This often happens if multiple ICU versions are installed or if library path environment variables (like `DYLD_LIBRARY_PATH` on macOS or `LD_LIBRARY_PATH` on Linux) are incorrectly set.

fix

Ensure that the ICU C++ library version used for building PyICU matches the one available at runtime. This typically involves reinstalling `icu4c` (e.g., `brew install icu4c` on macOS) and then reinstalling PyICU, often by setting explicit environment variables like `export LDFLAGS="-L$(brew --prefix)/opt/icu4c/lib" export CPPFLAGS="-I$(brew --prefix)/opt/icu4c/include"` before running `pip install pyicu`.

ImportError: cannot import name 'Locale' from 'icu'

This specific import error occurs when the Python interpreter finds the 'icu' module but cannot locate the `Locale` class within it. This can be due to a partial or corrupted PyICU installation, a version incompatibility, or a conflict with another package that might also try to provide an 'icu' module.

fix

First, ensure `pyicu` is the intended `icu` module by checking installed packages. If there are conflicts, try uninstalling other packages named 'icu' or 'PyICU'. Then, perform a clean reinstall of PyICU (`pip uninstall pyicu && pip install pyicu`) after verifying that system ICU dependencies are correctly installed.

Upgrade

Version history

2.16.2latest on PyPI · released Mar 20, 2026

Audit

Dependencies

ICU C++ librariesrequiredPyICU is a wrapper around the native ICU C++ libraries; these must be installed on the system for PyICU to function. The specific installation method varies by OS (e.g., Homebrew on macOS, apt on Debian/Ubuntu).

pkg-configrequiredUsed during compilation to locate the installed ICU C++ libraries.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

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

homepagehttps://gitlab.pyicu.org/main/pyicu ↗