pypinyin

What it is and what it does

pypinyin is a Chinese character-to-pinyin conversion library that transliterates hanzi (Chinese characters) into their romanized pronunciation forms. It handles context-aware pronunciation selection for multi-pronunciation characters (heteronyms), supports multiple output styles (tone marks, tone numbers, bopomofo notation, Wade-Giles romanization, initials/finals extraction), and includes a command-line tool for quick conversions.

The library uses embedded pinyin and phrase data to make intelligent decisions about which pronunciation to use based on word context. It supports both simplified and traditional Chinese, offers customizable output formatting, and allows users to override or extend the built-in pronunciation dictionaries. Common use cases include adding pronunciation annotations to Chinese text, sorting Chinese strings phonetically, and enabling search-by-pinyin functionality in applications.

Use it for:

• Add pinyin annotations above Chinese characters in educational materials or textbooks
• Implement search-by-pinyin functionality in applications handling Chinese text
• Sort lists of Chinese names or terms alphabetically by their pinyin pronunciation
• Extract initial consonants or final vowel sounds from Chinese characters for linguistic analysis
• Convert Chinese text to Wade-Giles or bopomofo notation for specialized linguistic or historical purposes
• Batch process Chinese documents to generate phonetic transcriptions for accessibility or text-to-speech systems

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Converts Chinese characters to pinyin (romanized pronunciation) with support for multiple styles, heteronyms, and tone marks.

Yes. pypinyin is a mature, actively maintained library with no known vulnerabilities, permissive licensing, and low installation friction. It is the standard tool for Chinese-to-pinyin conversion in Python and handles the complexity of context-aware pronunciation selection well. Install it if you need to work with Chinese character romanization; the only caveat is that accuracy depends on proper word segmentation and may require custom dictionary augmentation for domain-specific or rare characters.

Install

pypinyin on PyPI

pip install pypinyin

uv add pypinyin

poetry add pypinyin

Installing pypinyin

Before you install

Low friction installation with minimal dependencies. The package is actively maintained with a recent commit on 2026-07-20 and has accumulated 5352 stars, indicating stable, long-running community use.

License in practice

MIT license permits free use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart

pip install pypinyin

from pypinyin import pinyin, lazy_pinyin, Style

# Basic conversion
result = pinyin('中心')
# Returns: [['zhōng'], ['xīn']]

# With heteronyms (multiple pronunciations)
result = pinyin('中心', heteronym=True)
# Returns: [['zhōng', 'zhòng'], ['xīn']]

# Different style (first letter only)
result = pinyin('中心', style=Style.FIRST_LETTER)
# Returns: [['z'], ['x']]

Verify before relying

• Whether the package's pinyin accuracy is sufficient for production use without custom dictionary augmentation
• Performance characteristics when processing large volumes of Chinese text
• Behavior with rare or non-standard Chinese characters not in the bundled dictionaries

Package facts

Evidence: pypinyin-0.55.0-py2.py3-none-any.whl

Keywords: pinyin, 拼音

Tags

More Utilities packages