{"id":7569,"library":"pyicu-binary","title":"PyICU Binary","description":"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.","status":"active","version":"2.7.4","language":"en","source_language":"en","source_url":"https://github.com/wtolson/pyicu-binary","tags":["internationalization","i18n","unicode","locale","ICU","binary","text processing"],"install":[{"cmd":"pip install pyicu-binary","lang":"bash","label":"Install latest binary wheel"}],"dependencies":[{"reason":"PyICU 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.","package":"ICU C++ Library","optional":true}],"imports":[{"note":"All functionalities are exposed through the top-level `icu` module.","symbol":"icu","correct":"import icu"},{"symbol":"Locale","correct":"from icu import Locale"},{"symbol":"Collator","correct":"from icu import Collator"},{"symbol":"BreakIterator","correct":"from icu import BreakIterator"}],"quickstart":{"code":"import icu\n\n# Get the default locale\ndefault_locale = icu.Locale.getDefault()\nprint(f\"Default Locale: {default_locale.getDisplayName()}\")\n\n# Create a specific locale and get its display name in the default locale\njapanese_locale = icu.Locale(\"ja_JP\")\nprint(f\"Japanese Locale Display Name: {japanese_locale.getDisplayName(default_locale)}\")\n\n# Perform collation (sorting) using a specific locale\ncollator = icu.Collator.createInstance(japanese_locale)\nwords = [\"りんご\", \"みかん\", \"バナナ\"]\nsorted_words = sorted(words, key=collator.getSortKey)\nprint(f\"Sorted Japanese words: {sorted_words}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions of PyICU when building from source."},{"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`.","message":"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.","severity":"breaking","affected_versions":"PyICU versions built with ICU 63.1 or newer."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Adopt Pythonic `try-except icu.ICUError` blocks for error handling instead of checking `UErrorCode` values.","message":"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.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","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.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'icu-config'"},{"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.","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.","error":"ImportError: libicui18n.so.XX: cannot open shared object file: No such file or directory"},{"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`.","cause":"The PyICU setup script could not automatically detect the installed ICU version and requires manual specification during the build process.","error":"RuntimeError: Please set the ICU_VERSION environment variable to the version of ICU you have installed."},{"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.","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.","error":"AttributeError: module 'icu' has no attribute 'Collator' (or similar for other ICU classes)"}]}