---
id: pypinyin
version: "0.55.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# pypinyin — 汉字拼音转换模块/工具.

License: permissive · Maintenance: active · Downloads: 1.8M/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.8M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

chinese character to pinyin conversion, hanzi romanization, chinese text pronunciation, pinyin converter, tone marks and heteronyms, chinese language processing, bopomofo notation, chinese-nlp, romanization, i18n

[View on SkillFed](https://skillfed.io/packages/pypinyin) · [View on PyPI](https://pypi.org/project/pypinyin/)