Coqui Text-to-Speech (TTS)

0.27.5 · active · verified Thu Apr 16

Coqui TTS is a deep learning library for advanced Text-to-Speech synthesis, supporting a wide range of models and languages. It enables tasks like voice cloning, multi-speaker TTS, and emotional speech generation. The current version is 0.27.5, and the library maintains an active development pace with frequent patch and minor releases.

Common errors

```
ModuleNotFoundError: No module named 'torch'
```
cause Since `coqui-tts` v0.27.4, PyTorch and related dependencies are no longer automatically installed, requiring manual installation.

fix Install PyTorch and Torchaudio explicitly for your system. E.g., `pip install torch==2.3.0 torchaudio==2.3.0 --index-url https://download.pytorch.org/whl/cpu` (for CPU) or replace `cpu` with your CUDA version (e.g., `cu121`).
```
TypeError: synthesize() got an unexpected keyword argument 'speaker_id'
```
cause The `speaker_id` argument for `synthesize()` was deprecated in v0.27.0 and might be removed or cause errors in newer versions.

fix Refactor your code to use the `speaker_wav` argument or other model-specific parameters for speaker selection, as `speaker_id` is no longer the recommended approach.
```
RuntimeError: XTTS inference failed due to transformers version incompatibility. Please ensure transformers is within the supported range.
```
cause Certain versions of the `transformers` library cause issues with Coqui TTS models, particularly XTTS.

fix Check the Coqui TTS release notes for the recommended `transformers` version for your `coqui-tts` release. You might need to downgrade or upgrade `transformers`, e.g., `pip install transformers==4.51.0` or `pip install "transformers>=5.0.0"`.
```
AttributeError: 'TTS' object has no attribute 'speakers'
```
cause This error often occurs when trying to access `tts.speakers` for models that do not support explicit speaker IDs or have a different interface for speaker management (e.g., XTTS uses `speaker_wav`).

fix Verify if the loaded model actually supports multiple speakers via `tts.speakers`. For models like XTTS, you typically provide a `speaker_wav` file directly instead of selecting from an indexed list of speakers. Consult the documentation for your specific model.

Warnings

breaking Starting from v0.27.4, `coqui-tts` no longer installs `torch`, `torchaudio`, and `torchcodec` by default. Users must install these PyTorch dependencies manually to match their system (CPU/CUDA) and desired PyTorch version.
Fix: After `pip install coqui-tts`, manually install PyTorch and Torchaudio, e.g., `pip install torch==X.Y.Z torchaudio==X.Y.Z --index-url https://download.pytorch.org/whl/cuXXX` (for CUDA) or `.../whl/cpu` (for CPU). Refer to PyTorch's official installation instructions for specific versions.
breaking The old caching mechanism for Bark and Tortoise models has been removed. Additionally, the `speaker_id` argument in the `synthesize()` method is deprecated.
Fix: Switch to the new speaker caching mechanism (consult official documentation for updated cloning details). Avoid using `speaker_id` and prefer `speaker_wav` or other model-specific parameters for speaker selection.
gotcha Compatibility issues can arise with the `transformers` library, leading to incorrect output or inference errors. Specific `transformers` versions might be required for certain `coqui-tts` releases.
Fix: Check the Coqui TTS release notes or GitHub issues for recommended `transformers` versions. For example, v0.26.2 restricted transformers to `<4.52`, while v0.27.5 fixed issues with `transformers>=5`. If you encounter issues, try pinning `transformers` to a known working version.
gotcha Coqui TTS has strict Python version requirements, currently `<3.15,>=3.10`.
Fix: Ensure your Python environment is within the supported range. Create a new virtual environment with a compatible Python version if necessary (e.g., Python 3.10, 3.11, 3.12, 3.13).

Install

pip install coqui-tts pip install torch==2.3.0 torchaudio==2.3.0 --index-url https://download.pytorch.org/whl/cpu Basic CPU installation (post v0.27.4)
pip install coqui-tts pip install torch==2.3.0 torchaudio==2.3.0 --index-url https://download.pytorch.org/whl/cu121 CUDA 12.1 installation (post v0.27.4)
pip install 'coqui-tts[all]' Install all optional dependencies (pre v0.27.4, or if you manage PyTorch manually)

Imports

TTS
wrong:
```
from coqui_tts.tts import TTS
```
correct:
```
from TTS.api import TTS
```
The primary API is exposed through TTS.api, not lower-level internal modules.

Quickstart

This quickstart demonstrates how to initialize a Coqui TTS model and synthesize speech to an audio file. It uses a default VITS model for English. Remember to install PyTorch and Torchaudio manually if using coqui-tts versions 0.27.4 or newer. Adjust `gpu=True` for GPU acceleration if available and configured.

from TTS.api import TTS
import os

# This will download and load a default VITS model into memory.
# For GPU, set gpu=True. Ensure appropriate PyTorch version is installed.
# If you encounter issues, try a different model_name, e.g., 'tts_models/multilingual/multi-dataset/xtts_v2'
# For XTTS, you'd also need a speaker_wav file.
# For simpler, single-speaker models, speaker_wav is often optional.

tts = TTS(model_name="tts_models/en/ljspeech/vits", progress_bar=True, gpu=False)

# Synthesize speech to a file.
# Replace 'output.wav' with your desired output path.
output_file = "coqui_output.wav"
tts.tts_to_file(
    text="Hello from Coqui TTS, the ultimate text-to-speech library!",
    file_path=output_file,
    language="en"
)

print(f"Speech saved to {os.path.abspath(output_file)}")

view raw JSON →