Install & Compatibility
Where this runs
tested against v0.9.4 · 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
py 3.10
✕ build_error
✓ 88.3s
py 3.11
✕ build_error
✓ 85.83s
py 3.12
✕ build_error
✓ 71.1s
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✕ build_error
5154MB installed
● package 5154MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
G2P
✓ from misaki import en
✗ from misaki import en
Initializes the Misaki G2P engine for English and processes a sample text to obtain its phonemic representation. It demonstrates basic usage without optional transformer models or external fallbacks, with commented-out code showing how to integrate `espeak-ng` for out-of-dictionary word handling.
from misaki import en
# Initialize G2P for American English, no transformer, no external fallback
g2p = en.G2P(trf=False, british=False, fallback=None)
text = "Misaki is a G2P engine designed for Text-to-Speech models."
phonemes, tokens = g2p(text)
print(f"Text: {text}")
print(f"Phonemes: {phonemes}")
# Example with espeak-ng fallback (requires espeak-ng installed on system)
# from misaki import espeak
# fallback_espeak = espeak.EspeakFallback(british=False)
# g2p_with_fallback = en.G2P(trf=False, british=False, fallback=fallback_espeak)
# text_ood = "Now outofdictionary words are handled by espeak."
# phonemes_ood, _ = g2p_with_fallback(text_ood)
# print(f"Text (OOD): {text_ood}")
# print(f"Phonemes (OOD): {phonemes_ood}")
Debug
Known issues
breakingMisaki version 0.9.4 and higher currently do not support Python 3.13, and there have been reports of installation issues with other Python versions. Best compatibility is typically found with Python 3.10 or 3.11.fixUse Python 3.10 or 3.11 environments. Check the project's GitHub issues for updated compatibility information before attempting Python 3.13+.
affects: >=0.9.4
gotchaThe `espeak-ng` library, commonly used as a fallback for out-of-dictionary words in Misaki, is an external system dependency. It must be installed separately from the Python package, and its installation method varies by operating system (e.g., `apt-get install espeak-ng` on Debian/Ubuntu). Failure to install it will result in words not found in Misaki's internal dictionaries being spelled out letter-by-letter or marked as unknown.fixEnsure `espeak-ng` is installed at the system level for your specific OS if you intend to use it as a fallback. Refer to `espeak-ng` documentation for installation instructions.
affects: All versions
gotchaThe phoneme set used by Misaki for English is specifically designed for optimal performance in neural networks and may not strictly adhere to traditional linguistic IPA representations. The author notes that some symbols might be 'butchered or reappropriated'. This can lead to unexpected phoneme mappings for linguists or users expecting strict IPA compliance.fixConsult the `EN_PHONES.md` file in the Misaki GitHub repository to understand the specific phoneme set and its mappings if precise linguistic accuracy is critical. Be aware that the phonemes are optimized for machine learning models.
affects: All versions
gotchaEnabling transformer-based POS tagging (`trf=True`) or installing `misaki` as a dependency for other libraries like KittenTTS can pull in heavy dependencies such as `torch` and NVIDIA CUDA packages, potentially adding several gigabytes to the installation size, even if a GPU is not utilized or if `trf=False` is ultimately used for Misaki itself.fixBe mindful of your `pip install` commands. If you do not require transformer-based POS tagging, explicitly try to install `misaki` without extras that might trigger these large dependencies, or consider pruning the environment after installation if the extra packages are not needed by other parts of your project.
affects: All versions with `spacy-curated-transformers` dependency
gotchaMisaki's current implementation may have limitations in non-POS-based homograph disambiguation (e.g., distinguishing 'graph axes' from 'throwing axes'). While it handles some POS-based disambiguation, more complex contextual disambiguation remains a 'TODO'.fixFor text with ambiguous homographs that rely on deep semantic understanding, Misaki might produce incorrect phonemes. Users should be aware of this limitation and potentially pre-process such text or manually specify pronunciations using the Markdown-like syntax `[word](/phonemes/)` if high accuracy is required for such cases.
affects: All versions
Upgrade
Version history
0.9.4latest on PyPI · released Apr 5, 2025
Audit
Dependencies
espeak-ngoptionalOptional but highly recommended external system dependency for robust out-of-dictionary (OOD) word fallback. Installation varies by OS.
phonemizer-forkrequiredRequired for `misaki[en]` extra for advanced phonemization capabilities.
spacy-curated-transformersoptionalPulled in if using `misaki` with transformer-based POS tagging (e.g., `trf=True`) or via downstream dependencies like KittenTTS, which can introduce large `torch`/CUDA installations.