mozillazg

python-pinyin: Convert Chinese Characters to Pinyin

python-pinyin is a Python library for converting Chinese characters to pinyin for pronunciation, sorting, and search. It handles polyphonic characters and offers multiple romanization and annotation styles, including Zhuyin and Wade–Giles.

Stars
5.4k
Forks
632
Stars, last 30 days
+20
Last commit
15 days ago
Contributors
30

Our take

Activeregular commits

Health score

34/100

How it is scored
Activity
35
Community
40
Issues
33
Pull requests
29

+20 stars in the last 30 days

  • Slower to merge pull requests than 97% of the projects we track

A mature, actively maintained Python library with flexible pronunciation output, though teams should account for concentrated maintenance and slow issue closure.

Good fit if

  • You need Chinese-to-pinyin conversion in Python and value support for polyphonic characters and multiple output styles.
  • You can use its custom dictionaries or provide pre-segmented phrases to improve readings for your terminology.
  • You want an MIT-licensed library with recent commits and merged pull requests.

Look elsewhere if

  • Your deployment requires a release published within the last year, as the latest listed release is older than that.
  • Your team needs broadly distributed project ownership. Most measured contributions come from one person.
  • You need fast issue resolution: measured median time to close an issue is over a year.
All health signals
Last commit2026-11-01 (15 days ago)
Commits, last 90 days13
Releases, last 12 months0 (latest v0.55.0, 2025-07-20)
Contributors30 (top contributor: 90% of commits)
Issues closed, last 90 days4 (typically closed in 416 days)
Pull requests merged, last 90 days8 (typically merged in 20 days)
Project age13 years

Checked on 2026-11-17 with the GitHub API.

Project history

Daily GitHub snapshots since Oct 7, 2026. History covers stars and forks; health signals are not tracked historically.

Selected snapshot

Stars

5,395

Forks

632

Change since Nov 16, 2026: 0 stars·0 forks

Overview

python-pinyin is a Python library for converting Chinese characters to pinyin, aimed at applications that need pronunciation, sorting, or search support for Chinese text. It uses character and phrase pronunciation data to choose readings, which helps with polyphonic characters, and can also return other annotation styles such as Zhuyin and Wade–Giles.

The library provides both Python APIs and command-line utilities. It supports Python runtimes from 2.6 up to, but not including, 4 according to the project metadata. See the documentation for usage details and configuration options.

Key Features

  • Converts Chinese text to pinyin, using phrase matching to improve readings of polyphonic characters.
  • Offers pinyin and lazy_pinyin APIs, with an option to return multiple readings.
  • Supports tone marks, tone numbers, first letters, initials, finals, Zhuyin, and Wade–Giles styles.
  • Includes options for tone sandhi, neutral-tone notation, and representing ü with u rather than v.
  • Allows custom single-character and phrase dictionaries to adjust pronunciation results.
  • Provides command-line conversion and tone-conversion utilities.
  • Can leave characters without pinyin unchanged by default, with a documented hook for custom handling.

Use Cases

  • Chinese-language application developers can add pinyin pronunciations to text for display or speech-related workflows.
  • Search and indexing systems can use pinyin forms to support alternate ways of finding Chinese text.
  • Data-processing scripts can generate pinyin keys for sorting or grouping Chinese names and terms.
  • Language-learning or reference tools can display tone-marked pinyin, tone numbers, or Zhuyin annotations.
  • Teams with domain-specific vocabulary can load custom dictionaries when the default reading is unsuitable.

What you need

Detected in the repository

  • Python >=2.6, !=3.0.*, !=3.1.*, !=3.2.*, <4 (from pyproject.toml)
  • A test suite and automated checks on GitHub Actions

License in plain words

MITpermissive

  • Commercial use: yes
  • Modify and redistribute: yes
  • You must keep: the copyright and license notice
  • Share your changes: no

A summary, not legal advice: the LICENSE file is what applies.

Getting Started

Install from PyPI:

pip install pypinyin

See the README and documentation for examples and configuration details.

Considerations

The project is not archived and has recent commits, but it has had no release in over a year. Contribution is heavily concentrated in one person, and measured issue closure is slow, so consider your support and maintenance expectations before adopting it. Pronunciation depends on the supplied character and phrase data and on segmentation; the README documents custom dictionaries and pre-segmented input as ways to address incorrect readings. The project metadata states a broad Python runtime range, so check compatibility against your own supported interpreter versions and test the styles and edge cases your application needs.

Found this useful?

Share it with someone who would like python-pinyin.