---
id: xpinyin
version: "0.7.7"
license: MIT
license_treatment: permissive
maintenance: aging
---

# xpinyin — Translate Chinese hanzi to pinyin (拼音) by Python, 汉字转拼音

License: permissive · Maintenance: aging · Downloads: 73.6K/mo

## What it is and what it does

xpinyin is a Python library that translates Chinese characters into pinyin (the standard romanization system for Mandarin). It provides methods to extract the full phonetic spelling of characters, their initial consonants, and tone information in multiple formats—tone marks, tone numbers, or unmarked. The library also supports generating all possible pinyin combinations for characters with multiple readings, which is useful for disambiguation in mixed-reading contexts.

The package has no external dependencies and installs cleanly on modern Python versions. It's designed for developers building Chinese text processing pipelines, search systems, or applications that need to work with phonetic representations of Chinese text. The API is straightforward: instantiate a Pinyin object and call methods like get_pinyin(), get_initial(), or get_initials() with optional parameters to control output format.

Use it for:

- Building search indexes that allow users to find Chinese text by typing pinyin instead of characters
- Generating phonetic guides or furigana-style annotations for Chinese text in educational applications
- Implementing text-to-speech systems that need to convert hanzi to romanized pronunciation
- Sorting or organizing Chinese text alphabetically by pinyin for catalogs or directories
- Disambiguating characters with multiple pronunciations in natural language processing pipelines

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Converts Chinese characters (hanzi) to their phonetic romanization (pinyin), with support for tone marks, initial consonants, and multiple character readings.

Yes, if you need reliable Chinese-to-pinyin conversion. The package is stable, dependency-free, and covers the core use cases well. The aging maintenance status (438 days since last release) is not a blocker—the code is mature and the repository remains active—but monitor it if you depend on ongoing feature development or rapid bug fixes.

## Install

pip install xpinyin
uv add xpinyin
poetry add xpinyin

## Installing xpinyin

Before you install: Low friction installation with no runtime dependencies. Maintenance is aging—last release was 438 days ago—but the repository remains active with recent commits and the package has been stable since its 2011 inception.

License in practice: MIT license permits free use, modification, and distribution with minimal restrictions, making it suitable for both open-source and commercial projects.

Quickstart:

pip install xpinyin

from xpinyin import Pinyin
p = Pinyin()
p.get_pinyin("上海")
# Returns: 'shang-hai'
p.get_pinyin("上海", tone_marks='marks')
# Returns: 'shàng-hǎi'

Verify before relying:

- Whether the package handles simplified vs. traditional Chinese character variants consistently
- Performance characteristics when processing large documents or streams of text
- Completeness of the pinyin database for rare or archaic characters

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: aging
- Downloads: 73.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

chinese hanzi to pinyin conversion, pinyin romanization library, chinese character phonetic, tone marks and initials, chinese text processing, hanzi romanization, pinyin with tone numbers, chinese-nlp, romanization, text-processing

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