{"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":"python","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,"search_vec":"'2.7.4':7 'aim':42 'api':27 'binari':2,5,40,80,88,96 'built':16,90 'bypass':56 'c':26 'compat':87 'compil':62 'complex':59 'compon':30 'distribut':41 'extens':22 'i18n':92 'icu':25,28,68,95 'instal':45,67 'intern':29 'internation':37,91 'librari':69 'local':94 'offer':33 'often':58 'packag':11 'platform':55 'pre':15 'pre-built':14 'process':60,98 'project':74,85 'provid':13,47 'pyicu':1,4,19,63,73,79 'pyicu-binari':3,78 'python':10,21 'readi':49 'ready-to-us':48 'regular':76 'releas':81 'robust':34 'see':75 'separ':66 'servic':38 'simplifi':44 'text':97 'track':82 'unicod':32,35,93 'updat':77 'upstream':72,84 'use':51 'various':54 'version':6 'wheel':17,52 'wrap':23","created_at":"2026-04-16T14:03:59.765642+00:00","updated_at":"2026-04-16T14:03:59.765642+00:00","problems":{"verify_error":"× Failed to build `pyicu-binary==2.7.4`\n  ├─▶ The build backend returned an error\n  ╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit\n      status: 1)\n\n      [stdout]\n      (running 'icu-config --version')\n\n      Building PyICU 2.7.4 for ICU 73.2 (max ICU major version supporte"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.7.4","cli_name":"","cli_version":null,"type":"library","homepage":"https://gitlab.pyicu.org/main/pyicu","github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/pyicu-binary/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"install_fail","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-05","install_tag":null}}