Install & Compatibility
Where this runs
tested against v0.55.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.620s · 21.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.568s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pinyin
✓ from pypinyin import pinyin
Main function for converting Chinese characters to Pinyin, returning a list of lists with tone marks by default.
lazy_pinyin
✓ from pypinyin import lazy_pinyin
Function for converting Chinese characters to Pinyin, returning a flat list without tone marks or heteronyms by default.
Style
✓ from pypinyin import Style
Enum containing various Pinyin output styles (e.g., TONE, FIRST_LETTER, TONE2, BOPOMOFO).
Demonstrates basic conversion of Chinese characters to Pinyin using `pinyin` and `lazy_pinyin` functions, including handling different styles and heteronyms.
from pypinyin import pinyin, lazy_pinyin, Style
chinese_text = "你好，世界！"
# Convert to Pinyin with tone marks (default style)
pinyin_result_toned = pinyin(chinese_text)
print(f"Toned Pinyin: {pinyin_result_toned}")
# Convert to Pinyin without tone marks (lazy_pinyin)
pinyin_result_lazy = lazy_pinyin(chinese_text)
print(f"Lazy Pinyin: {pinyin_result_lazy}")
# Convert to Pinyin using first letter style
pinyin_result_first_letter = pinyin(chinese_text, style=Style.FIRST_LETTER)
print(f"First Letter Pinyin: {pinyin_result_first_letter}")
# Handle heteronyms (multi-pronunciation characters)
heteronym_text = "中心"
pinyin_heteronym = pinyin(heteronym_text, heteronym=True)
print(f"Heteronym Pinyin for '中心': {pinyin_heteronym}")
Debug
Known issues
gotchaBy default, pypinyin results do not indicate neutral tones and use 'v' for 'ü'.fixTo include neutral tones (as '5'), use `neutral_tone_with_five=True`. To use 'ü' instead of 'v', set `v_to_u=True` when calling `lazy_pinyin` or `pinyin` (for non-tone styles).
affects: All versions (default behavior)
gotchaStandard Pinyin rules state that 'y', 'w', and 'yu' are not syllable initials. By default, pypinyin adheres to this, which might lead to unexpected empty strings for `Style.INITIALS`.fixIf you need 'y', 'w', 'yu' to be counted as initials, pass `strict=False` to the `pinyin` or `lazy_pinyin` function. This is particularly relevant for `Style.INITIALS`.
affects: All versions (default behavior)
gotchaWhen converting text containing characters without Pinyin (e.g., symbols, non-Chinese characters), the default behavior is to return them as-is.fixUse the `errors` parameter to control this behavior: `errors='ignore'` to remove them, `errors='replace'` to substitute with Unicode, `errors='exception'` to raise `PinyinNotFoundException`, or provide a callable for custom handling.
affects: All versions (default behavior)
breakingIn Python 3.12, older versions of pypinyin (prior to 0.52.0) experienced significant performance degradation during import, especially in debugging environments or with `pytest --cov`.fixUpgrade to `pypinyin` version 0.52.0 or newer. This version changed data loading from in-memory dicts to JSON files to mitigate the issue.
affects: <0.52.0 on Python 3.12
gotchaWhen bundling applications with PyInstaller, older versions of pypinyin might have had issues locating internal data files, leading to `no such file or dictionary: pinyin_dict.json` errors.fixUpgrade to `pypinyin` version 0.53.0 or newer, which includes built-in support for PyInstaller bundling, resolving common data file path issues.
affects: <0.53.0 with PyInstaller
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pypinyin'
The 'pypinyin' library has not been installed in the current Python environment.
ImportError: cannot import name 'Pinyin' from 'pypinyin'
The 'pinyin' function is incorrectly imported with an uppercase 'P' (Pinyin) instead of the correct lowercase 'p' (pinyin).
fixfrom pypinyin import pinyin, Style
TypeError: pinyin() got an unexpected keyword argument 'strict'
The 'strict' keyword argument was removed from the 'pinyin()' function in pypinyin version 0.50.0 and is no longer supported.
fixRemove the 'strict' argument from the pinyin() function call; its functionality has been integrated or replaced.
AttributeError: type object 'Style' has no attribute 'TONE_UNKNOWN'
An invalid or misspelled Pinyin style constant was used, or the 'Style' enum was not correctly imported or referenced.
fixEnsure the Pinyin style constant is a valid member of the 'pypinyin.Style' enum, such as 'Style.TONE' or 'Style.NORMAL'.
AttributeError: module 'pypinyin' has no attribute 'STYLE_NORMAL'
You are attempting to access Pinyin style constants using an older, deprecated syntax (e.g., `pypinyin.STYLE_NORMAL`).
fixImport the `Style` enum and use its attributes: `from pypinyin import pinyin, Style` then `pinyin('你好', style=Style.NORMAL)`. Upgrade
Version history
0.55.0latest on PyPI · released Jul 20, 2025
Audit
Dependencies
No dependency data recorded yet.