# python-pinyin: A Robust Python Library for Hanzi to Pinyin Conversion

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/mozillazg-python-pinyin
Generated for open source discovery and AI-assisted research.

`python-pinyin` is a powerful Python library designed for converting Chinese characters (Hanzi) into Pinyin. It offers advanced features such as intelligent phrase matching, comprehensive support for polyphonic characters, and various Pinyin and Bopomofo output styles. This tool is essential for developers working on Chinese text processing tasks, including annotation, sorting, and search functionalities.

GitHub: https://github.com/mozillazg/python-pinyin
OSRepos URL: https://osrepos.com/repo/mozillazg-python-pinyin

## Summary

`python-pinyin` is a powerful Python library designed for converting Chinese characters (Hanzi) into Pinyin. It offers advanced features such as intelligent phrase matching, comprehensive support for polyphonic characters, and various Pinyin and Bopomofo output styles. This tool is essential for developers working on Chinese text processing tasks, including annotation, sorting, and search functionalities.

## Topics

- python
- pypinyin
- chinese
- hanzi
- pinyin
- Natural Language Processing
- Utilities

## Repository Information

Last analyzed by OSRepos: Sat Aug 01 2026 01:59:50 GMT+0100 (Western European Summer Time)
Detail views: 4
GitHub clicks: 0

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## Introduction

`python-pinyin` is a powerful Python library developed by mozillazg that facilitates the conversion of Chinese characters (Hanzi) into Pinyin. It is widely used for various applications, including annotating Chinese text, sorting data, and enabling efficient search functionalities. The library stands out for its intelligent phrase matching, comprehensive support for polyphonic characters, and flexibility in outputting different Pinyin and Bopomofo styles.

## Installation

You can easily install `python-pinyin` using pip:

bash
pip install pypinyin


Alternatively, if you use `uv`, you can install it with:

bash
uv add pypinyin


## Examples

Here are some examples demonstrating the versatility of `python-pinyin`:

python
from pypinyin import pinyin, lazy_pinyin, Style

# Basic conversion
print(pinyin('??'))
# Output: [['zh?ng'], ['x?n']]

# Enable polyphonic character mode
print(pinyin('??', heteronym=True))
# Output: [['zh?ng', 'zhòng'], ['x?n']]

# Set Pinyin style (e.g., first letter)
print(pinyin('??', style=Style.FIRST_LETTER))
# Output: [['z'], ['x']]

# Bopomofo style
print(pinyin('??', style=Style.BOPOMOFO))
# Output: [['???'], ['???']]

# Lazy Pinyin (no tone marks, single result per character)
print(lazy_pinyin('??'))
# Output: ['zhong', 'xin']


## Why Use `python-pinyin`?

`python-pinyin` offers several compelling reasons for developers working with Chinese text:

*   **Accuracy**: It intelligently matches the most correct Pinyin based on phrases and provides comprehensive support for polyphonic characters, ensuring high accuracy in conversions.
*   **Flexibility**: The library offers a wide range of Pinyin and Bopomofo styles, including options for tone marks, first letters, and Wade-Giles, catering to diverse linguistic and application requirements.
*   **Customization**: Users can easily customize phrase and single-character Pinyin dictionaries to correct or optimize conversion results. It also integrates seamlessly with external Pinyin data projects for enhanced accuracy.
*   **Comprehensive Features**: Beyond basic conversion, `python-pinyin` includes utilities for Pinyin style conversion, command-line tools, and extensive documentation covering common FAQs and advanced usage scenarios.
*   **Robust and Maintained**: Developed by mozillazg, the project benefits from active maintenance and a strong community, ensuring reliability and ongoing improvements.

## Links

*   Official Documentation: [https://pypinyin.readthedocs.io/](https://pypinyin.readthedocs.io/)
*   GitHub Repository: [https://github.com/mozillazg/python-pinyin](https://github.com/mozillazg/python-pinyin)
*   PyPI Project Page: [https://pypi.org/project/pypinyin](https://pypi.org/project/pypinyin)