Open Chinese Convert (OpenCC) Python Bindings

Common errors

• ImportError: No module named 'opencc'

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

• OSError: libopencc.so.1.1.0: cannot open shared object file: No such file or directory

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

• FileNotFoundError: [Errno 2] No such file or directory: 's2t.json'

  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).
  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).

• ERROR: Failed building wheel for OpenCC

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

• TypeError: 'module' object is not callable

  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.
  fix from opencc import OpenCC converter = OpenCC('s2tw.json') # Or use import opencc; converter = opencc.OpenCC('s2tw.json')

Warnings

• gotcha 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.
  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`.
• breaking 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.
  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.
• deprecated 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.
  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.

Install

• pip install OpenCC Install official OpenCC Python bindings

Imports

• OpenCC

  from opencc import OpenCC

Quickstart

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.

from opencc import OpenCC

# Initialize converter: Simplified Chinese to Traditional Chinese (Taiwan Standard)
# Available configs: 's2t.json', 't2s.json', 's2tw.json', 'tw2s.json', 's2hk.json', 'hk2s.json', 's2twp.json'
converter = OpenCC('s2tw.json')

# Text to convert
simplified_text = "鼠标键盘，开放中文转换。"

# Perform conversion
traditional_text = converter.convert(simplified_text)

print(f"Simplified: {simplified_text}")
print(f"Traditional (Taiwan): {traditional_text}")

# Example with another conversion: Traditional Chinese to Simplified Chinese
another_converter = OpenCC('t2s.json')
trad_hk_text = "滑鼠鍵盤，開放中文轉換。"
simplified_output = another_converter.convert(trad_hk_text)
print(f"Traditional (HK): {trad_hk_text}")
print(f"Simplified: {simplified_output}")