Install & Compatibility
Where this runs
tested against v? · pip install
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.940 runs
timeout
glibcpy 3.10–3.940 runs
timeout
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TTS
✓ from TTS.api import TTS
This quickstart demonstrates how to initialize a TTS model (e.g., a Tacotron2 model for English) and synthesize speech to an audio file, automatically detecting and utilizing a GPU if available. It includes basic error handling and hints for common issues.
import torch
from TTS.api import TTS
# Determine device (CUDA if available, otherwise CPU)
device = "cuda" if torch.cuda.is_available() else "cpu"
print(f"Using device: {device}")
# Initialize TTS with a common English model (will download if not available)
try:
tts = TTS(model_name="tts_models/en/ljspeech/tacotron2-DDC", device=device)
# Generate speech and save to file
text_to_synthesize = "Hello, this is a test from the Coqui TTS library."
output_filepath = "output_audio.wav"
tts.tts_to_file(text=text_to_synthesize, file_path=output_filepath)
print(f"Speech synthesized to {output_filepath}")
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure you have installed TTS and its dependencies correctly.")
print("For GPU support, install torch with CUDA first (e.g., pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu118)")
tts --version
Debug
Known issues
breakingThe primary API for model inference shifted significantly around versions 0.20.0-0.21.0. Older approaches that involved directly importing and instantiating model classes (e.g., `from TTS.vocoder.models.wavernn import WaveRNN`) are largely superseded by the unified `TTS` class from `TTS.api`. While some direct imports might still function, the recommended and supported way to load and use models is via `TTS.api.TTS(model_name='...')`.fixMigrate your code to use `from TTS.api import TTS` and load models by their string identifiers (e.g., `tts = TTS(model_name='tts_models/en/ljspeech/tacotron2-DDC')`).
affects: Before ~0.20.0
gotchaModels like XTTS v2 are highly resource-intensive, requiring substantial GPU VRAM (e.g., 10GB+) and system RAM (16GB+). Running these models on CPU or under-resourced GPUs can lead to `CUDA out of memory` errors or extremely slow inference speeds.fixEnsure you have adequate hardware resources (GPU with sufficient VRAM). Consider using smaller models or CPU inference if hardware is limited (though CPU will be much slower for large models).
affects: All versions with XTTS models
gotchaMany multilingual and advanced TTS models rely on external system-level dependencies like `espeak-ng` and `ffmpeg` for phonemization and audio processing. These are not installed by `pip` and must be manually installed on your operating system.fixInstall `espeak-ng` and `ffmpeg` via your system's package manager (e.g., `sudo apt-get install espeak-ng ffmpeg` on Debian/Ubuntu, `brew install espeak-ng ffmpeg` on macOS).
affects: All versions
gotchaAchieving GPU acceleration requires careful management of `torch`, `torchaudio`, and CUDA toolkit versions. Installing `tts` via `pip` usually pulls in CPU versions of `torch` and `torchaudio` if GPU-enabled versions are not pre-installed. Mismatched versions can lead to `CUDA not available` or runtime errors.fixExplicitly install `torch` and `torchaudio` with the correct CUDA index-url *before* installing `tts`. For example, `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118`. Always refer to PyTorch's official installation guide for your specific CUDA version.
affects: All versions
Upgrade
Version history
0.22.0latest on PyPI · released Dec 12, 2023
Audit
Dependencies
torchrequiredCore deep learning framework for model execution. Specific versions are critical for CUDA compatibility.
torchaudiorequiredAudio processing library, tightly coupled with torch. Specific versions are critical for CUDA compatibility.