Registry / ai-ml / kokoro

kokoro

JSON →
library0.9.4pypypiunverified

Kokoro is a Python library for Text-to-Speech (TTS) synthesis, leveraging ONNX models for efficient audio generation. It provides a straightforward API to convert text into spoken audio. As of version 0.9.4, it targets Python 3.10-3.12 and is under active development, with releases occurring as new features or bug fixes are integrated.

pip install kokoro
INSTALL
IMPORT
SIG · KOKORO
K
kokoro
ai-mlpythonv0.9.4
Install
80.1s avg
Import
Disk
5325MB
Pass rate
1/ 10
Env Coverage1 / 10
glibc
3.93.13
musl
3.93.13
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
musl
glibc
py 3.10
✕ build_error
✕ timeout
py 3.11
✕ build_error
✕ timeout
py 3.12
✕ build_error
✓ 80.14s
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✕ build_error
5325MB installed
● package 5325MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

TextToSpeech
from kokoro.tts import TextToSpeech

This quickstart demonstrates how to initialize the `TextToSpeech` model and synthesize audio. It requires you to first download an ONNX model file (`.onnx`) and its corresponding configuration file (`.json`) from the official Hugging Face repository, as these are not bundled with the package. Ensure the paths are correctly set before running.

import os from kokoro.tts import TextToSpeech from scipy.io.wavfile import write # IMPORTANT: Model assets are NOT included in the package. # Download a model and config from https://huggingface.co/hexgrad/kokoro_models # For example, 'hexgrad/kokoro_models/tree/main/vits/vctk_ljs' # Placeholder paths - REPLACE with actual paths to your downloaded files model_path = os.environ.get('KOKORO_MODEL_PATH', 'path/to/your_model.onnx') config_path = os.environ.get('KOKORO_CONFIG_PATH', 'path/to/your_config.json') if not os.path.exists(model_path) or not os.path.exists(config_path): print(f"Error: Model or config files not found.\n") print(f"Please download them from https://huggingface.co/hexgrad/kokoro_models\n") print(f"And set KOKORO_MODEL_PATH and KOKORO_CONFIG_PATH environment variables, or update the script.\n") exit(1) try: tts = TextToSpeech(model_path=model_path, config_path=config_path) audio = tts.synthesize("Hello, this is a test from the Kokoro library.") # Save the generated audio sampling_rate = tts.config.sampling_rate # Access sampling_rate from the loaded config output_filename = "kokoro_output.wav" write(output_filename, sampling_rate, audio) print(f"Audio saved to {output_filename}") except Exception as e: print(f"An error occurred during TTS synthesis: {e}") print("Ensure your model_path and config_path are correct and the ONNX runtime is properly installed.")
kokoro --version
Debug
Known issues
gotchaModel and configuration files are NOT included in the Kokoro package. Users MUST manually download an ONNX model (`.onnx`) and its corresponding config file (`.json`) from the official Hugging Face repository (e.g., `huggingface.co/hexgrad/kokoro_models`) before synthesis.
fix
Download the desired model and config files, then provide their full paths to the `TextToSpeech` constructor.
affects: All
breakingThe `onnxruntime` dependency requires careful installation for CPU vs. GPU. Installing `pip install kokoro` provides CPU-only support. For GPU acceleration, `pip install kokoro[gpu]` is required, along with a compatible CUDA setup. Mismatched `onnxruntime` versions or attempting to use GPU without `[gpu]` extra will lead to errors like 'Failed to find provider 'CUDAExecutionProvider''.
fix
For CPU: `pip install kokoro`. For GPU: ensure `nvcc --version` shows CUDA, then `pip install kokoro[gpu]`.
affects: All
gotchaKokoro strictly requires Python versions 3.10, 3.11, or 3.12. Using unsupported versions (e.g., Python 3.9 or 3.13) will result in installation failures or runtime errors due to dependency constraints.
fix
Use a Python environment manager (e.g., `conda` or `pyenv`) to set up a compatible Python version (3.10, 3.11, or 3.12) for your project.
affects: All
gotchaSynthesizing long texts or using very large models can lead to high memory (RAM/VRAM) consumption, potentially causing out-of-memory errors on systems with limited resources.
fix
For long texts, consider splitting them into smaller segments. Monitor resource usage and, if necessary, choose smaller ONNX models that require less memory.
affects: All
Upgrade
Version history
0.9.4latest on PyPI · released Apr 5, 2025
Audit
Dependencies
onnxruntimerequiredCore dependency for running ONNX models (CPU backend by default).
onnxruntime-gpuoptionalEnables GPU acceleration for ONNX models when installed via `kokoro[gpu]`.
Agent activity
13 hits · last 30 days
node
12
Resources
kokoro — pip install kokoro · libregistry