Install & Compatibility
Where this runs
tested against v0.5.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
py 3.10
✕ build_error
✓ 13.45s
py 3.11
✕ build_error
✓ 8.25s
py 3.12
✕ build_error
✓ 7.6s
py 3.13
✕ build_error
✓ 7.65s
py 3.9
✕ build_error
✕ build_error
232MB installed
● package 232MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Kokoro
✓ from kokoro_onnx import Kokoro
This quickstart demonstrates how to initialize the `Kokoro` class, generate speech from text, and save the output to a WAV file. It is crucial to manually download the `kokoro-v1.0.onnx` and `voices-v1.0.bin` model files from the official GitHub releases and place them in the same directory as your script, or provide their full paths.
import os
import soundfile as sf
from kokoro_onnx import Kokoro
# --- IMPORTANT: Download model files first ---
# Download 'kokoro-v1.0.onnx' and 'voices-v1.0.bin' from:
# https://github.com/thewh1teagle/kokoro-onnx/releases/tag/model-files-v1.0
# Place them in the same directory as this script, or specify full paths.
# -----------------------------------------------
MODEL_PATH = os.environ.get('KOKORO_MODEL_PATH', 'kokoro-v1.0.onnx')
VOICES_PATH = os.environ.get('KOKORO_VOICES_PATH', 'voices-v1.0.bin')
# Ensure model files exist before proceeding
if not os.path.exists(MODEL_PATH) or not os.path.exists(VOICES_PATH):
print(f"Error: Model files not found. Please download '{MODEL_PATH}' and '{VOICES_PATH}'")
print("from https://github.com/thewh1teagle/kokoro-onnx/releases/tag/model-files-v1.0")
print("and place them in the current directory or set KOKORO_MODEL_PATH/KOKORO_VOICES_PATH.")
exit(1)
try:
# Initialize Kokoro with model and voice files
kokoro = Kokoro(MODEL_PATH, VOICES_PATH)
# Text to synthesize
text = "Hello, this is a test from kokoro-onnx. How are you today?"
# Generate speech (default voice is often 'am_michael')
# You can list available voices via kokoro.get_voices()
samples, sample_rate = kokoro.create(text, voice='af_alloy')
# Save the audio to a WAV file
output_filename = "audio.wav"
sf.write(output_filename, samples, sample_rate)
print(f"Speech generated and saved to {output_filename}")
except Exception as e:
print(f"An error occurred: {e}")
print("Ensure 'onnxruntime' and 'soundfile' are installed and model files are correct.")
Debug
Known issues
breakingModel files (`.onnx` and `.bin`) are mandatory for the application to start. If these files are missing or incorrectly located, the application will exit with an error.fixDownload `kokoro-v1.0.onnx` and `voices-v1.0.bin` from the latest model-files release (e.g., `thewh1teagle/kokoro-onnx/releases/tag/model-files-v1.0`) and ensure they are accessible by the application, either in the script directory or via specified paths.
affects: All versions
gotchaUsers have reported issues with GPU acceleration using the DirectML execution provider on Windows, often resulting in 'Non-zero status code returned while running ConvTranspose node' errors. CUDA execution provider on Linux (e.g., WSL) seems to work better.fixOn Windows, consider using the CPU execution provider, or if on Linux, ensure CUDA/cuDNN are correctly set up and use `onnxruntime-gpu`.
affects: All versions where DirectML is used
gotchaA memory leak issue has been reported when synthesizing longer sentences, where memory is not released after synthesis. This might be an upstream model issue, but it impacts `kokoro-onnx` usage.fixMonitor memory usage for long text generations. Consider processing text in shorter segments if feasible, or restarting the process for critical applications.
affects: 0.4.6 and potentially later versions
deprecatedIn related `kokoro-onnx` integrations (e.g., `pipecat-ai`'s `KokoroTTSService`), direct parameters like `voice_id` and `params` in the constructor are being deprecated in favor of a `settings` object (e.g., `settings=KokoroTTSService.Settings(...)`). This indicates an evolving API design pattern.fixRefer to the latest documentation or examples for the recommended way to configure voice and other parameters, favoring a `settings` object if available.
affects: Potentially future `kokoro-onnx` versions or directly affects integrations built on it.
Upgrade
Version history
0.5.0latest on PyPI · released Jan 30, 2026
Audit
Dependencies
onnxruntimerequiredCore dependency for running ONNX models. The CPU version is installed by default; GPU versions (e.g., onnxruntime-gpu) can be installed separately.
numpyrequiredNumerical operations, especially for handling audio data.
soundfilerequiredRequired for saving generated audio to WAV files, as demonstrated in quickstart examples.
phonemizer-forkoptionalFor grapheme-to-phoneme conversion, improving pronunciation quality.
espeakng-loaderoptionalAlternative or complementary dependency for grapheme-to-phoneme conversion.