{"id":8371,"library":"opencc","title":"Open Chinese Convert (OpenCC) Python Bindings","description":"OpenCC (Open Chinese Convert) is an open-source project designed for high-quality conversions between Traditional Chinese, Simplified Chinese, and Japanese Kanji (Shinjitai). The Python `opencc` library provides C++ bindings, enabling character-level and phrase-level conversion, character variant handling, and adaptation to regional idioms. The current version is 1.2.0, with an active release cadence reflecting updates to the underlying C++ library.","status":"active","version":"1.2.0","language":"en","source_language":"en","source_url":"https://github.com/BYVoid/OpenCC","tags":["chinese","conversion","traditional-simplified","nlp","text-processing","language"],"install":[{"cmd":"pip install OpenCC","lang":"bash","label":"Install official OpenCC Python bindings"}],"dependencies":[],"imports":[{"symbol":"OpenCC","correct":"from opencc import OpenCC"}],"quickstart":{"code":"from opencc import OpenCC\n\n# Initialize converter: Simplified Chinese to Traditional Chinese (Taiwan Standard)\n# Available configs: 's2t.json', 't2s.json', 's2tw.json', 'tw2s.json', 's2hk.json', 'hk2s.json', 's2twp.json'\nconverter = OpenCC('s2tw.json')\n\n# Text to convert\nsimplified_text = \"鼠标键盘，开放中文转换。\"\n\n# Perform conversion\ntraditional_text = converter.convert(simplified_text)\n\nprint(f\"Simplified: {simplified_text}\")\nprint(f\"Traditional (Taiwan): {traditional_text}\")\n\n# Example with another conversion: Traditional Chinese to Simplified Chinese\nanother_converter = OpenCC('t2s.json')\ntrad_hk_text = \"滑鼠鍵盤，開放中文轉換。\"\nsimplified_output = another_converter.convert(trad_hk_text)\nprint(f\"Traditional (HK): {trad_hk_text}\")\nprint(f\"Simplified: {simplified_output}\")","lang":"python","description":"This quickstart demonstrates how to import the `OpenCC` class, initialize a converter with a specific configuration (e.g., Simplified Chinese to Traditional Chinese for Taiwan Standard), and perform text conversion. It also shows an example of converting Traditional Chinese to Simplified Chinese."},"warnings":[{"fix":"Always use `pip install OpenCC` for the official C++-based library. If you specifically need a pure Python implementation, use `pip install opencc-python-reimplemented`.","message":"There are multiple Python packages related to OpenCC, including `opencc` (the C++ bindings), `opencc-python-reimplemented` (a pure Python version), and older `opencc-python` wrappers. Ensure you install `OpenCC` (with a capital 'O') for the official C++ bindings to avoid unexpected behavior or compatibility issues.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For `OSError`, ensure your system's `LD_LIBRARY_PATH` includes the directory containing `libopencc.so`, or that the library is installed in a standard system path. On some Debian/Ubuntu systems, `sudo apt-get install opencc-tools` may install the necessary shared library. If building from source, ensure all build dependencies are met and the linker finds the correct version. For `Segmentation fault`, it might indicate an ABI mismatch; try reinstalling `OpenCC` in a clean environment.","message":"The `opencc` library is a C++ binding. On some Linux systems, or when building from source, users may encounter `OSError: libopencc.so: cannot open shared object file` or `Segmentation fault` errors due to issues with the underlying C++ library (`libopencc`) not being found or correctly linked. This often occurs if system-wide `libopencc` is an older version or if Python cannot locate the bundled shared library.","severity":"breaking","affected_versions":"All versions, especially when installing on Linux or from source."},{"fix":"If possible, use Python 3.12 or earlier where wheels are readily available. If Python 3.13/3.14 is required, ensure you have a C++ compiler (e.g., GCC on Linux, Xcode on macOS, MSVC on Windows) and CMake installed and configured for your environment. Monitor the GitHub repository for new wheel releases for these Python versions.","message":"As of Python 3.13 and 3.14, pre-built wheels for `opencc` are currently unavailable. Users attempting to install on these Python versions will typically trigger a source build, which can fail if necessary C++ build tools (like CMake and a C++ compiler) are not installed or configured correctly.","severity":"deprecated","affected_versions":"1.2.0 and earlier with Python 3.13, 3.14+"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify `pip install OpenCC` succeeded. If you intended the pure Python version, install `pip install opencc-python-reimplemented` and import as `from opencc_purepy import OpenCC`. Check for conflicting local files named `opencc.py`.","cause":"This error most commonly occurs when trying to import the `opencc` C++ bindings but either the installation failed, or another package (like `opencc-python-reimplemented`) was intended and installed under a different name, or a local file named `opencc.py` shadows the installed package.","error":"ImportError: No module named 'opencc'"},{"fix":"Ensure the OpenCC C++ library is correctly installed and its path is discoverable by the Python environment. On Linux, this might involve installing a system package like `opencc-tools` or adding the library's directory to `LD_LIBRARY_PATH`.","cause":"The Python `opencc` binding cannot locate the underlying C++ shared library (`libopencc.so`). This can happen if the library is not installed on the system, or if it's installed in a non-standard location not included in `LD_LIBRARY_PATH` (on Linux/macOS) or `PATH` (on Windows).","error":"OSError: libopencc.so.1.1.0: cannot open shared object file: No such file or directory"},{"fix":"Double-check the configuration file name for typos. Ensure the `OpenCC` library was installed correctly and its data files are accessible. If using a custom config or data directory, you might need to provide a full path or explicitly set the `data_path` parameter (though typically not needed for standard configs).","cause":"The specified configuration file (e.g., 's2t.json') was not found by the `OpenCC` constructor. This can happen if the configuration name is misspelled or if the library's data files are not installed in the expected location (e.g., if the installation was incomplete or a custom configuration path is needed).","error":"FileNotFoundError: [Errno 2] No such file or directory: 's2t.json'"},{"fix":"Ensure you have a C++ compiler (like `build-essential` on Debian/Ubuntu, Xcode Command Line Tools on macOS, or MSVC on Windows) and CMake installed. If on a very new Python version, consider using an older, supported Python version or checking the OpenCC GitHub for updates on wheel availability.","cause":"This error indicates that `pip` attempted to compile the `opencc` package from source, but the compilation failed. This is common on Python versions for which pre-built wheels are not yet available (e.g., Python 3.13, 3.14+) or if required C++ build tools (compiler, CMake) are missing.","error":"ERROR: Failed building wheel for OpenCC"},{"fix":"from opencc import OpenCC\nconverter = OpenCC('s2tw.json') # Or use import opencc; converter = opencc.OpenCC('s2tw.json')","cause":"You are attempting to call the `opencc` module directly as a function, but the conversion functionality is provided by the `OpenCC` class within the module.","error":"TypeError: 'module' object is not callable"}]}