Install & Compatibility
Where this runs
tested against v1.4.2 · 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.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 7.5s · import 0.339s · 226MB
190MB installed
● package 190MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PiperVoice
✓ from piper import PiperVoice
SynthesisConfig
✓ from piper.voices import SynthesisConfig
✗ from piper import SynthesisConfig
SynthesisConfig resides in the 'voices' submodule since v1.3.0.
This quickstart demonstrates how to load a Piper TTS voice model and synthesize speech. Remember that model files (`.onnx` and `.json`) must be downloaded separately. The `synthesize` method yields audio chunks (bytes) that can then be processed, saved, or played back.
import piper
import os
# NOTE: Model files (.onnx and .json) are NOT included with the pip package.
# You MUST download them separately, e.g., from huggingface.co/rhasspy/piper-voices
# Example: 'en_US-lessac-medium.onnx' and 'en_US-lessac-medium.json'
# Provide paths to your downloaded model files
model_path = os.environ.get('PIPER_MODEL_PATH', 'path/to/your_downloaded_model.onnx')
config_path = os.environ.get('PIPER_CONFIG_PATH', 'path/to/your_downloaded_model.json')
if not os.path.exists(model_path) or not os.path.exists(config_path):
print(f"Error: Model files not found. Please download '.onnx' and '.json' files.")
print(f" Expected model at: {model_path}")
print(f" Expected config at: {config_path}")
print(f" Download example: https://huggingface.co/rhasspy/piper-voices/tree/main")
else:
try:
# Load the voice model
voice = piper.PiperVoice.load(model_path, config_path=config_path)
# Get default synthesis configuration
synthesis_config = voice.config.synthesis
text = "Hello, this is a test from Piper TTS."
print(f"Synthesizing: '{text}'")
audio_chunks_generator = voice.synthesize(text, synthesis_config)
num_chunks = 0
for audio_bytes in audio_chunks_generator:
num_chunks += 1
# In a real application, you would save audio_bytes to a file
# or stream it for real-time playback (e.g., using 'sounddevice').
# Example: print(f"Received chunk of {len(audio_bytes)} bytes.")
pass # Just iterate to demonstrate generation
print(f"Successfully generated {num_chunks} audio chunks.")
print("Audio can be saved to a WAV file using Python's 'wave' module or 'soundfile'.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Errors
Common errors & fixes
FileNotFoundError: [Errno 2] No such file or directory: 'path/to/model.onnx'
The Piper TTS model (.onnx) or its configuration file (.json) was not found at the specified path. These files are not installed with the pip package.
fixDownload the desired model and config files (e.g., from huggingface.co/rhasspy/piper-voices) and ensure the `model_path` and `config_path` arguments to `PiperVoice.load()` are correct.
AttributeError: 'PiperVoice' object has no attribute 'synthesize_raw'
The `synthesize_raw` method was removed in version 1.3.0 as part of an API overhaul.
fixMigrate your code to use the `PiperVoice.synthesize()` method. It now takes a `piper.voices.SynthesisConfig` object (e.g., `voice.config.synthesis`) and yields audio bytes directly.
TypeError: PiperVoice.synthesize() missing 1 required positional argument: 'config'
Since Piper TTS v1.3.0, the `synthesize` method requires a `piper.voices.SynthesisConfig` object as its second argument.
fixPass a `SynthesisConfig` object, typically obtained from the loaded voice (`voice.config.synthesis`), as the second argument: `voice.synthesize(text, voice.config.synthesis)`.
Upgrade
Version history
1.4.2latest on PyPI · released Apr 2, 2026
Audit
Dependencies
onnxruntimerequiredCore inference engine for ONNX models.
espeak-ngrequiredSystem-level C library required for phonemization unless using pre-generated phoneme IDs. While Piper embeds its Python bindings, the underlying system library is often still needed.