Install Piper TTS v1.4.2: Open Source TTS Guide

Here’s a detail almost every open source TTS tutorial got wrong in the last few months: the Piper repo you’re probably about to git clone is archived. rhasspy/piper went read-only in October 2025, the license flipped from MIT to GPL-3.0, and active work now lives at OHF-Voice/piper1-gpl under the Open Home Foundation. If you’re deploying an open source TTS engine in 2026, that one detail changes your install command, your dependency chain, and – depending on what you’re building – your licensing obligations.

This guide walks through installing the current release (piper-tts 1.4.2 on PyPI, as of early 2026), skipping the traps that broke older tutorials.

Why the license switch actually matters

Piper is a VITS-based neural TTS engine: espeak-ng turns your text into phonemes, a neural network synthesizes audio from those phonemes, and the whole thing runs via ONNX runtime – small enough to hit real-time on a Pi 5 with no GPU. What changed is governance and packaging. The original rhasspy/piper repository (MIT-licensed) was archived read-only in October 2025; active development moved to OHF-Voice/piper1-gpl, which is GPL-3.0. If your project needs a permissive MIT license specifically, you’d be pinning the old archived code – the current, maintained Piper is GPL-3.0.

Commercial users, heads up: Shipping Piper inside a closed-source product triggers GPL-3.0’s reciprocal obligations. The MIT-era binaries are still on GitHub, but they stopped getting fixes in October 2025 – including for ONNX protobuf parse errors community users hit on newer voice files. If staying closed-source is non-negotiable, you need a different voice engine or a legal review.

The v1.3.0 release (per the OHF-Voice release notes) removed the old C++ code, moved development to Python, and embedded espeak-ng directly rather than relying on the separate piper-phonemize library. That last move quietly killed the single most common install failure from 2024 – more on that in the errors section.

System requirements

Piper is deliberately modest. Python 3.9+ on x86_64 or aarch64 is the baseline. Here’s the practical minimum vs. what you actually want:

Real-time synthesis on a Raspberry Pi 5 with no GPU is confirmed (Local AI Master benchmark, 2025). No CUDA needed at inference time.

Install open source TTS with pip (recommended path)

One command. This is the piper-tts 1.4.2 wheel from PyPI, which bundles the ONNX runtime and the embedded espeak-ng bridge:

python3 -m venv piper-env
source piper-env/bin/activate
pip install piper-tts

No separate piper-phonemize, no tarball extraction, no LD_LIBRARY_PATH gymnastics. Turns out the build approach is the reason: scikit-build-core compiles a Python module that wraps espeak-ng via a small espeakbridge.c using Python’s stable ABI. One wheel per platform (Linux, Mac, Windows) instead of one per platform-plus-Python-version combination. The wheel just works on Linux x86_64/aarch64, macOS Intel and Apple Silicon, and Windows x64.

Download a voice next. The models live in the Hugging Face rhasspy/piper-voices repo (which was not archived – voice files are still the canonical source):

mkdir -p ~/piper-voices && cd ~/piper-voices
wget https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_US/amy/medium/en_US-amy-medium.onnx
wget https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_US/amy/medium/en_US-amy-medium.onnx.json

You always need both files, in the same directory. The .json holds sample rate, phoneme mapping, and default length_scale – Piper won’t start without it.

First run and verification

piper --version
# Should print 1.4.2 or newer

echo "The install works." | piper 
 --model ~/piper-voices/en_US-amy-medium.onnx 
 --output_file test.wav

aplay test.wav

If test.wav plays back as speech, you’re done. If not, the next section covers the errors worth knowing.

The install errors that eat hours

Most horror stories online describe the old stack. These are the ones still relevant:

1. ResolutionImpossible: piper-phonemize conflict. Seeing piper-tts 1.2.0 depends on piper-phonemize~=1.1.0 means you’re installing an ancient version. Documented across GitHub issues #509, #395, and #725: pip on macOS ARM would fail with “Cannot install piper-tts==1.1.0 and piper-tts==1.2.0 because these package versions have conflicting dependencies” and “Could not find a version that satisfies the requirement piper-phonemize==1.1.0”. Fix: pip install --upgrade piper-tts and confirm you’re on 1.4.2 or newer. The new version doesn’t need piper-phonemize at all.

2. ONNX “Protobuf parsing failed” on load. Classic wget trap. Community reports point to two causes: the voice file downloaded incompletely over a flaky connection, or wget followed the Hugging Face HTML redirect and saved an HTML page instead of the ONNX blob. Check with file en_US-amy-medium.onnx – it should say “data”, not “HTML document”. Re-download with ?download=true appended to the Hugging Face URL.

3. Choppy or skipped audio on Raspberry Pi 5. A recurring thread on discussion #359: generated speech comes out jumbled when writing to WAV. The workaround is bypassing the WAV write entirely and streaming raw audio directly to aplay:

echo "Testing streaming output." | piper 
 --model ~/piper-voices/en_US-amy-medium.onnx 
 --output-raw | aplay -r 22050 -f S16_LE -t raw -

4. Home Assistant TTS silent on long messages. Using Piper through the Wyoming protocol in HA? TTS messages longer than about 35 seconds fail to play on the target speaker – anything shorter works fine. The Wyoming stream drops with a ConnectionResetError (documented in home-assistant/addons issue #3360). Chunk your messages or split announcements into multiple tts.speak calls.

Configuration knobs worth knowing

Two settings handle 90% of tuning. Both live in the voice’s .onnx.json file, or can be passed as CLI flags:

• length_scale – speech speed. Default is 1.0. Higher is slower. 1.2-1.5 sounds natural for narration; 0.9 for snappy voice-assistant replies.
• noise_scale – prosody randomness. Set to 0 and Piper sounds robotic but deterministic; leave at default and the same input has small variations each run. On some voices the variation occasionally produces awkward deliveries – swap the voice model rather than fighting the parameter.

Multi-speaker voices take --speaker <int> from 0 to N-1. The libritts voices ship with dozens of speaker IDs in a single file – efficient, but without --speaker you always get ID 0.

Which raises a question worth sitting with before you go further: does your project actually need a custom voice, or will one of the 30+ pretrained voices cover the use case? Fine-tuning is doable, but it’s a multi-day GPU job. Browsing the official samples page first has saved a lot of people that detour.

Training your own voice (brief note)

The training path also moved. The standard approach is to fine-tune from a pre-trained checkpoint – it cuts training time dramatically and improves quality compared to starting cold. Pre-trained checkpoints are at huggingface.co/datasets/rhasspy/piper-checkpoints (per the piper1-gpl training docs). For hardware: the training docs note that --batch-size 32 and --max-phoneme-ids 400 fits 24 GB of vRAM (RTX 3090/4090) – note this references the older TRAINING.md from the archived repo, so specifics may have changed with the OHF-Voice migration. A 12 GB card needs the batch size halved and phoneme cap lowered, with roughly double the time per epoch.

Fine-tuning on ~30 minutes of clean audio is realistic on a single 4090 in a day or two. From scratch is a different animal – rarely worth it now that the checkpoint zoo is public.

Upgrade and uninstall

Upgrading from piper-tts 1.2.0 or earlier: those versions dragged in piper-phonemize as a separate wheel. Clean it out first:

pip uninstall -y piper-tts piper-phonemize
pip install piper-tts

Your existing .onnx voice files transfer directly – no re-download. To remove Piper entirely, pip uninstall piper-tts and delete your voices directory.

FAQ

Is Piper still MIT-licensed?

No. The current maintained version at OHF-Voice/piper1-gpl is GPL-3.0. Only the archived rhasspy/piper repo is MIT, and it stopped getting updates in October 2025.

Can I use Piper commercially without releasing my source code?

Depends on how you ship it. Running Piper as a backend service you never distribute? Generally fine under GPL – the copyleft clause kicks in when you distribute binaries, not when you run a server. Bundling it into a shipped desktop app or embedded device is where GPL-3.0 gets complicated: derivative works must also be GPL-3.0. That’s a real constraint, not a theoretical one. Ask a lawyer before you ship.

Does Piper support voice cloning like XTTS or ElevenLabs?

Not zero-shot. Cloning in Piper means recording 20-60 minutes of a target voice, preparing a metadata CSV, and running a fine-tune job on a GPU. More work upfront – but the output quality per byte at inference time tends to beat zero-shot cloners, which is why embedded and screen-reader applications (NVDA, Home Assistant) use it.

Next step: pick a voice from the official samples page, listen to five candidates in your target language, download the two files, and get piper --version printing on your machine before the end of the hour.